Parameter Descriptions

The parameter descriptions are listed in alphabetical order. Default values are underlined:

,ANSAREA=ansarea

Use this output area to contain information about the request. The storage area is mapped by the IXLYRTAA macro and must be addressable in the caller's primary address space.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of an output area is to contain information about the request.

,ANSLEN=anslen

Use this input area to specify the length of the ANSAREA storage area.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a halfword input field that specifies the length of ANSAREA.

CONTOKEN=contoken

Use this input parameter to specify the connect token of the requestor. The token is the connect token that was returned to the requestor by the IXLCONN service. CONTOKEN uniquely identifies the user's connection to a lock structure.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a 16-character input field that contains the connect token returned in the answer area by the IXLCONN service.

,DATAREA=datarea

Use this output area to contain the data returned by a READALL or READBYCONN request. This area must be 4096 bytes long and is mapped by the IXLYMRTD macro.

Upon successful completion of a READALL or READBYCONN request, DATAREA contains, starting at offset zero, an array of records containing 64 bytes of record data, the entry identifier (ENTRYID) for the element that was successfully read, and the connection identifier (CONID) of the connected user who is associated with each element that was successfully read. Additional information may also be provided, based on the MRTDLEVEL requested. The number of record data entries returned is indicated in the answer area specified by ANSAREA, mapped by IXLYRTAA.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a 4096-byte output area to contain the data returned by a READALL or READBYCONN request.

,ENTRYID=entryid

Use this input/output parameter to specify the identifier assigned to the record data entry.

For a CREATENTRY request, this identifier is returned by IXLRT and must be used on all subsequent requests to access the record data entry.

For READENTRY and DELETENTRY requests, this identifier specifies the unique entry identifier assigned to the record data entry.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a 12-character input/output field that contains the entry identifier.

,ENTRYIDLIST=entryidlist

Use this input parameter to identify an area that contains a list of record data entry identifiers to be processed by the DELETENTRYLST request. This list must be aligned on a page boundary and be 4096 bytes long. The ENTRYIDLIST must be formatted into 12-byte elements starting at offset zero. Each record data entry to be processed consists of a 12-byte identifier.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a 4096-byte input area to contain a list of record data entry identifiers to be processed by a DELETENTRYLIST request.

,EXTRESTOKEN=extrestoken

Use this input/output parameter to specify an extended restart token that can be used to resume processing of all READALL, READBYCONN, and DELETEBYCONN requests. Requestors that specify IXLCONN ALLOWAUTO=YES must use the extended restart token. Requestors that specify or default to IXLCONN ALLOWAUTO=NO must use the standard restart token (RESTOKEN).

You must provide an initial value of zero in this field. The system then initializes the field with control information relevant to the READALL, READBYCONN, or DELETEBYCONN request. On each subsequent request, the system uses this information. You must not modify the contents of this field.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a 16-character input/output area to contain an extended restart token.

,FASTPATH=NO

,FASTPATH=YES

Use this input parameter to indicate that the system is to process this READBYCONN request using an optimized access method when accessing the record data.

NO: The system is not to use the optimized access method when accessing the record data.
YES: The system is to use the optimized access method when accessing the record data. Use FASTPATH=YES only when the caller has serialization that ensures that the record data entries belonging to the target connector will remain unchanged throughout the process.

,FASTRESTOKEN=fastrestoken

Use this input/output parameter to specify a 12-character field that must be passed on READBYCONN FASTPATH=YES requests.

You must provide an initial value of zero in the field. The system then initializes the field with control information. On each subsequent READBYCONN FASTPATH=YES request, the system uses this information. You must not modify the contents of this field.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a 12-character input/output field to contain control information.

,FIRSTELEM=1

,FIRSTELEM=firstelem

Use this input parameter to specify the index of the first ENTRYIDLIST element to be processed. The value specified must be in the range of 1 to 341 inclusive.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a halfword input field to contain the index of the first ENTRYIDLIST element to be processed.

,LASTELEM=lastelem

Use this input parameter to specify the index of the last ENTRYIDLIST element to be processed. The value must be in the range of 1 to 341 inclusive and must be greater than, or equal to, the value of FIRSTELEM.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a halfword input field to contain the index of the last ENTRYIDLIST element to be processed.

,MF=S

,MF=(L,mfctrl)

,MF=(L,mfctrl,mfattr)

,MF=(L,mfctrl,0D)

,MF=(E,mfctrl)

,MF=(E,mfctrl,COMPLETE)

Use MF=S to specify the standard form of the macro, which builds an inline parameter list and generates the macro invocation to transfer control to the service.

Use MF=L to specify the list form of the macro. Use the list form together with the execute form of the macro for applications that require reentrant code. The list form defines an area of storage that the execute form uses to store the parameters. Only the PLISTVER parameter can be coded with the list form of the macro.

Use MF=E to specify the execute form of the macro. Use the execute form together with the list form of the macro for applications that require reentrant code. The execute form stores the parameters into the storage area defined by the list form, and generates the macro invocation to transfer control to the service.

,mfctrl: Use this output parameter to specify a storage area to contain the parameters.
To Code: Specify the RS-type name or address (using a register from 2 to 12) of the parameter list.
,mfattr: Use this input parameter to specify the name of a 1- to 60-character string that can contain any value that is valid on an assembler DS pseudo-op. You can use this parameter to force boundary alignment of the parameter list. If you do not code mfattr, the system provides a value of 0D, which forces the parameter list to a doubleword boundary.
,COMPLETE: Use this input parameter to require that the system check for required parameters and supply defaults for omitted optional parameters.
Note: In the macro expansion you might see some defaults for optional parameters that are not documented here. The ones that are not documented do not have any effect on the macro. For example, if SMILE=var were an optional parameter and the default is SMILE=NO_SMILE then it would not be documented. However, if the default was SMILE=:-), then it would be documented because a value would be the default.

,MRTDLEVEL=0

,MRTDLEVEL=mrtdlevel

Use this input parameter to specify the level of MRTD data that is to be returned in the area specified by DATAREA. Valid values are 0 and 1.

A value of 0 indicates that the entries returned will be mapped by the MRTD mapping in IXLYMRTD.
A value of 1 indicates the entries returned will be mapped by the MRTD1 mapping in IXLYMRTD.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of the one-byte area containing the level of the IXLYMRTD record mappings.

,OUTRDATATYPE=outrdatatype

Use this output parameter to contain the record data type (RDATATYPE) value associated with the record data element that was returned for a READENTRY request.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of an 8-character field that will contain the returned record data element's record data type.

,PLISTVER=IMPLIED_VERSION

,PLISTVER=MAX

,PLISTVER=plistver

Use this input parameter to specify the version of the macro. See Understanding IXLRT Version Support for a description of the options available with PLISTVER.

,RDATATYPE=NO_RDATATYPE

,RDATATYPE=0

,RDATATYPE=rdatatype

Use this input paramter to specify the type of record data in the lock structure.

For a CREATENTRY request, RDATATYPE specifies the record data type that is to be assigned to the created record data entry. If a nonzero record data type value is not specified, a record data type of zero will be assigned to the entry. Note that record data that is created by the IXLLOCK service in conjuntion with a held lock resource has a record data type of zero. DEFAULT: 0.

For a READALL, READBYCONN, and DELETEBYCONN request, RDATATYPE specifies the record data type to be used as a filter for processing the record data entries. When specified, only those record data entries whose record data type matches the specified value will be selected for processing. Note that record data that is created by the IXLLOCK service in conjunction with a held lock resource has a record data type of zero. DEFAULT: NO_RDATATYPE.

For an UPDATENTRY request, RDATATYPE specifies the record data type to be assigned to the updated record data entry. The record data type can be the same as or different from that current record data type for the entry. If a nonzero record data type value is not specified, a record data type of zero will be assigned to the entry. Note that record data that is created by the IXLLOCK service in conjunction with a held lock resource has a record data type of zero. DEFAULT: 0

To Code: Specify the RS-type name or address (using a register from 2 to 12) of an 8-character field that contains the record data type.

,REQUEST=CREATENTRY

,REQUEST=READALL

,REQUEST=READBYCONN

,REQUEST=READENTRY

,REQUEST=DELETENTRYLST

,REQUEST=DELETENTRY

,REQUEST=DELETEBYCONN

,REQUEST=UPDATENTRY

Use this input parameter to specify the function requested.

CREATENTRY

Create a record data entry in the lock structure to which the caller is connected and write data to that entry.

When the request completes successfully, the unique entry identifier assigned by XES, the number of entries associated with the target connector, and the total number of in-use entries in the record data entry are returned in the answer area specified by ANSAREA.

READALL

Read the next group of record data entries associated with the lock structure to which the caller is connected.

When the request completes successfully, the number of entries for which record data was read is returned in the answer area specified by ANSAREA.

A READALL request may complete prematurely. If so, indicative return and reason codes are provided, the number of record data entries read is provided in the answer area, and a token is returned in the location specified by the RESTOKEN or EXTRESTOKEN keyword. This token may be specified as input on a subsequent READALL request to resume processing with the appropriate record data entry.

READBYCONN

Read the next group of record data entries associated with the specified connection name.

When the request completes successfully, the number of entries for which record data was read is returned in the answer area specified by ANSAREA.

A READBYCONN request may complete prematurely. If so, indicative return and reason codes are provided, the number of record data entries read is provided in the answer area, and a token is returned in the location specified by the RESTOKEN or EXTRESTOKEN keyword. This token may be specified as input on a subsequent READBYCONN request to resume processing with the appropriate record data entry.

READENTRY

Read a particular record data entry by entry identifier.

When the request completes successfully, the number of entries associated with the target connector and the total number of in-use record data entries are returned in the answer area specified by ANSAREA.

DELETENTRYLST

Delete all record data entries specified by a list of entry identifiers. This list of entry identifiers is specified by the ENTRYIDLIST keyword.

When the request completes successfully, the number of entries deleted for this request is returned in the answer area specified by ANSAREA.

A DELETENTRYLST request may complete prematurely. If so, indicative return and reason codes are provided, the number of record data entries deleted, and the index of the next entry to be deleted are provided in the ANSAREA. To continue deleting the remaining elements in the ENTRYIDLIST, the DELETENTRYLST request can be reissued with the FIRSTELEM keyword updated to indicate the new starting point in the element list.

If any entry specified in the ENTRYIDLIST does not exist, the processing is halted and the index of the offending element in the ENTRYIDLIST is also returned in the answer area. When this occurs, all specified elements preceding the offending element have been processed. All succeeding elements have not been processed. To continue deleting the remaining elements in the ENTRYIDLIST, the DELETENTRYLST request can be reissued with the FIRSTELEM keyword updated to indicate the new starting point in the element list.

DELETENTRY

Delete an existing record data entry by entry identifier.

When the request completes successfully, the remaining number of entries associated with the target connector and the remaining total number of in-use record data entries are returned in the answer area specified by ANSAREA.

DELETEBYCONN

Delete the next group of record data entries associated with the specified connection name.

When the request completes successfully, the number of entries for which record data was deleted is returned in the answer area specified by ANSAREA.

A DELETEBYCONN request may complete prematurely. If so, indicative return and reason codes are provided, the number of record data entries deleted is provided in the answer area, and a token is returned in the location specified by the RESTOKEN or EXTRESTOKEN keyword. This token may be specified as input on a subsequent DELETEBYCONN request to resume processing with the appropriate record data entry.

UPDATENTRY

Update an existing record data entry by entry identifier.

When the request completes successfully, the number of entries associated with the connector with whom the updated entry was associated and the total number of in-use record data entries are returned in the answer area specified by ANSAREA.

,RDATAVAL=rdataval

Use this input/output parameter to specify 64 bytes of user-defined data.

For a CREATENTRY request, the field contains user-defined data to be written to the record data entry.

For a READENTRY request, the field will contain the data returned from the record data entry.

For an UPDATENTRY request, the field contains the data with which to update the record data entry.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a 64-character input/output field to contain the user-defined data for a record data entry.

,RESTOKEN=restoken

Use this input/output parameter to specify a containing a standard restart token that must be passed on READALL, READBYCONN FASTPATH=NO, and DELETEBYCONN requests. Requestors that specify or default to IXLCONN ALLOWAUTO=NO must use the standard restart token. Requestors that specify IXLCONN ALLOWAUTO=YES must use the extended restart token (EXTRESTOKEN).

You must provide an initial value of zero in the field. The system then initializes the field with control information relevant to the READ or DELETE request. On each subsequent READ or DELETE request, the system uses this information. You must not modify the contents of this field.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of an eight-character input/output field to contain control information.

,RETCODE=retcode

Use this output parameter to specify the location in which the system is to copy the return code from GPR 15.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a fullword to contain the return code.

,RSNCODE=rsncode

Use this output parameter to specify the location in which the system is to copy the reason code from GPR 0.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a fullword to contain the reason code.

,TCONNAME=NO_TCONNAME

,TCONNAME=tconname

Use this input parameter to specify the target connection name (CONNAME) of the connected user. If a target connection name is not specified, the record data is associated with the connected user identified by the CONTOKEN keyword.

For a CREATENTRY request, the record data entry that is to be created will be associated with the connected user identified by the TCONNAME keyword.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a 16-character input field that contains the target connection name.

,VERCONNAME=NO_VERCONNAME

,VERCONNAME=verconname

Use this input parameter to specify the name of a connected user to be verified as the connector associated with the record data entry that is to be read. if the connector indicated by the VERCONNAME is not associated with the entry specified by ENTRYID, the IXLRT request fails.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a 12-character input field to contain the connection name to be verified.