Requesting block mode

 

You can use block mode to specify whether the system will be sending one or more journal entries to the exit program and specifies the block length of the buffer passed to the exit program.

When you request block mode, the system sends more than one journal entry to the exit program at a time. You can request block mode at any time. There are two ways that you can request block mode:

• Specify the BLKLEN parameter on the Receive Journal Entry (RCVJRNE) command

• Specify 8 for the value of the first byte of the second parameter of the exit program

 

BLKLEN parameter of the RCVJRNE command

When you specify the BLKLEN parameter of the RCVJRNE command you can select one of three values:

*NONE

At most one journal entry will be sent to the exit program.

*CALC

One or more journal entries will be passed to the exit program in a block. The length of the block passed (the first parameter passed to the exit program) is determined by the system and will be optimal.

block-length

Specify the length in kilobytes of the buffer passed to the exit program (EXITPGM parameter). Valid values range from 32 to 4000

If you specify BLKLEN(*CALC) or BLKLEN(block-length), specifying 8 in the first byte of the second parameter will have no impact and the first 5 bytes of the first parameter will be ignored.

 

Specifying 8 for the value of the first byte of the second parameter of the exit program

When you specify 8 for the value of the first byte of the second parameter, specify the block length in the first 5 bytes of the first parameter as a zoned decimal (Zoned (5,0)) field. 99999 bytes is the maximum block size. After you have requested block mode, the system remains in block mode until the RCVJRNE processing is ended.

If you request block mode and the system is already using block mode, your request is ignored. You cannot change the size of the block from the size you specified when you first requested block mode.

Even if BLKLEN(*NONE) is specified, if you specify 8 for the value of the first byte of the second parameter, the system will use block mode.

 

Format of the first Parameter

If the specified entry format is not *TYPEPTR or *JRNENTFMT, and if you are using single-entry mode, the format of the first parameter looks like the following figure:

First parameter of RCVJRNE command: Single-entry mode

The first 5 bytes contains the length of the entry. The last 5 bytes contains all zeroes. The length of the entry does not include the 5 bytes of zeroes at the end of the record.

If the specified entry format is not *TYPEPTR or *JRNENTFMT, and if you are using block mode, the format of the first parameter looks like the following figure:

First parameter of RCVJRNE command: Block mode

The first 5 bytes contains the total length of the block. This length includes the 5 bytes for the total block length, the 5 bytes of the End of Record field at the end of the block, and all of the length and data fields in between. If no entry is being passed, this Block Length field contains zeroes. The block always ends with a 5-byte End of Record field containing zeroes.

If you specify BLKLEN(*NONE), then the system fills the block with as many complete entries as it can fit within the block size that you specified. The system does not send a partial entry to fill the block size. If the specified entry format is not *TYPEPTR or *JRNENTFMT, the maximum number of bytes that are available for the journal entries is 99989 bytes. 10 bytes in each block are reserved for the Block Length field and for the End of Record field. If the specified entry format is *TYPEPTR or *JRNENTFMT, the maximum number of bytes that are available is 99999 bytes.

If you specify a block size that is not valid, the system begins block mode but it sends only one journal entry per block. The system sends message CPD7095 to indicate that you have specified a block size that is not valid. If you specify a block size that is not valid or too small for a single journal entry, the system still returns at least one journal entry to the exit program. If the specified entry format is *TYPEPTR or *JRNENTFMT, the block size must be at least 13 bytes to be considered valid.

 

When the System Sends a Record

When block mode is in effect, the system uses the following rules to determine when to call the exit program:

• If the block does not contain any entries but the next entry would exceed the maximum size for the block, then the entry is placed into the block. The exit program is called. The system always passes at least one complete journal entry to the exit program.

• If the next entry to be put into the block would exceed the maximum size for the block and the current block has entries in it, then the current block of entries is passed to the exit program.

• If the current block has one or more entries in it and no additional entries in the journal meet the selection criteria, the current block of entries is passed to the exit program.

When in block mode, the specification for the DELAY parameter is used only when the current block is empty and no entries are currently available to be returned to the exit program.

 

Using ENTFMT(*TYPEPTR) or ENTFMT(*JRNENTFMT) with the RCVJRNE command

If the specified entry format is *TYPEPTR or *JRNENTFMT, the layout of the journal entry data is the same as the layout that is described in the QjoRetrieveJournalEntries API interface. The layout is the same for both single entry and block entry mode when you specify *TYPEPTR or *JRNENTFMT.

If you specify *TYPEPTR, the format will be the same as the RJNE0100 format of the QjoRetrieveJournalEntries API.

When you specify *TYPEPTR or *JRNENTFMT, the journal entry data may have pointers that will point to additional entry-specific data.

 

Parent topic:

Receiving journal entries in an exit program

Related concepts
Exit program to receive journal entries Working with pointers in journal entries

Related reference
Receive Journal Entry (RCVJRNE) command Retrieve Journal Entries (QjoRetrieveJournalEntries) API