General Description

The IOAMEM module attributes are

RENT, AMODE=31 RMODE=24

Upon entry, the value of AMODE is saved. AMODE is set to 31 to handle addresses above the 16MB line. Upon return, the original value of AMODE is restored.

Storage for the handler is obtained below the 16 MB line and is saved in the handler address. The caller must not modify the handler address between the first call and the FINISH request call to module IOAMEM.

The handler address is returned in field IMHNDLR, which is mapped by macro IOAMMEM.

When invoking macro IOAMEM with parameter HANDLE=addr, the field that contains the handler address is not modified by macro IOAMEM. If more than one handler is used in the same program, save the handler address and invoke macro IOAMEM with the proper handler address in parameter HANDLE=addr.

It is not necessary to provide a buffer address for GETMEM, DIRECTOR, DIRALL, and DIRFULL requests.

If the buffer address is not passed (field value is zero), module IOAMEM obtains storage above or below the 16MB line. The number of records in the storage buffer is determined as follows:

• If field RECNUM (IMRECNUM) is not zero, then the number of records is the value in field RECNUM (IMRECNUM).
• If field RECNUM (IMRECNUM) is zero, then the default number of records is 5000.

The actual buffer size is the number of records in the buffer times the LRECL of the input dataset, plus 16 bytes for the header.

Module IOAMEM does not free any buffer the caller uses. If module IOAMEM obtains a storage buffer address on behalf of a caller, the caller must free this storage. The caller can free the buffer by using macro IOAXAGR. Field IMBUFARD points to the real buffer address + 16 bytes. The length of the buffer is in offset 4 from the beginning of the header.

If the buffer address is passed (field value is not zero), IOAMEM treats the value of IMRECNUM as the actual buffer size (in records). Therefore, to prevent storage protection violations, do NOT specify a value of IMRECNUM that exceeds the actual buffer size (in records).

If the buffer address is passed (field value is not zero) and the buffer size is insufficient, module IOAMEM ends with a return code of 08 and a reason code of 24. The actual number of records the member contains is returned in field IMRECNUM.

If the buffer address is not passed (field value is zero), module IOAMEM returns with a buffer that contains the entire member. The number of records in the buffer is returned in field IMRECNUM.

Macro IOAMEM checks whether parameter IOAMEMA has been supplied. If this parameter has been supplied, macro IOAMEM uses the supplied address. Otherwise, macro IOAMEM loads the IOAMEM module before invoking it and deletes it upon return.

GETMEM, GETLINE and PUTMEM requests support reading and writing members with record lengths other than 80 bytes. The GETLINE request can read members with variable record lengths.

The DIRECTOR, DIRALL, and DIRFULL functions accept a member name in the MEMBER sub-parameter of the IOAMEM macro. The member name may include masking characters. For example

All members are included in the directory list (the same as a null MEMBER= parameter or MEMBER=0)

All members that begin with the character A and have a total length of at least 2 characters are included in the directory list.

The DIRALL request provides similar functionality as the DIRECTOR function and additionally supports concatenated files for the given DD name. When DIRECTOR is used, each buffer entry length is 11 bytes — 8 bytes for the member name, and 3 bytes for the TTR. When DIRALL is used, each buffer entry length is 52 bytes — 8 bytes for the member name, and 44 bytes for the library name in which the member exists.

The FINISH request cleans up the environment, closes all opened DCBs, and frees all I/O buffers and the handler storage.

Module IOAMEM must be called with a FINISH request. Otherwise, some DCBs may remain open and some storage buffers may remain allocated.

When trying to access a DFHSM migrated dataset, IOAMEM will behave as follows:

• If the RECALL parameter was set to YES, access will be done with an automatic recall (all address spaces will wait until the dataset is recalled), and no further action will be required by the caller.
• If the RECALL parameter was set to NO (default), IOAMEM will decide what to do based upon the MCTENV flag. Note that the MCT address must be passed to IOAMEM (MCTADDR parameter).
  • If MCTENV is MCTENVSE (IOA online monitor) or MCTENV1 is MCTENVAS (IOA application server), then IOAMEM will submit a RECALL request to DFHSM and will return to its caller with RC=4 RSN=8 (see details of codes below). If, for some reason, the request fails, the regular RC is returned (RC=16 RSN=32).
  • If MCTENV is MCTENVON (IOA online session) or MCTENV is MCTENVKS (KSL environment) or MCTENV2 is MCTENVBU (CONTROL-B batch utilities), the behavior will be the same as if the RECALL parameter was set to YES, even when it was set to the default (NO).

The parameter list passed to IOAMEM is mapped by the IOAMMEM macro as follows:

Table 324 Mapping of Parameter List by IOAMMEM Macro

Table 325 Return Codes and Reason Codes

Table 326 Return Codes and Reason Codes (GETMEM, GETLINE, PUTMEM)

Table 327 Return Codes and Reason Codes (ALLOC, DEALLOC)

Table 328 Return Codes, Reason Codes and Descriptions

Table 329 Return Codes and Reason Codes from Librarian/Panvalet