DESERV parameters

Table 1 and Table 2 show the DESERV macro parameters and indicate for each function if the parameter is required, optional, or invalid. The figure applies to the MF=S (standard) forms of the macro, or to the logically merged MF=L and MF=E parameters.

AREA=(buffer_area,buffer_area_size)  buffer_area—MF=S form, RX–type address or (2-12)  buffer_area—MF=L form, A–type address)  buffer_area—MF=E form, RX–type Address or (2-12)

Specifies an area provided by the caller into which the GET, GET_G, and GET_ALL_G functions store directory entries.

The area is mapped by the DESB DSECT in the IGWDES mapping macro on return from the function. The storage must be modifiable in the key of the caller.

AREA and AREAPTR are mutually exclusive.

If the area is filled before the processing has ended, the request is terminated at that point. The entries in the buffers are valid and connections may have been established.

For the GET_G and GET_ALL_G functions, to retrieve additional entries, a subsequent GET_G or GET_ALL_G request can be made with name_list specifying the generation name within the last generation directory entry returned in the buffer area.

  buffer_area_size—Symbol or (2-12)
  absexp or (2-12)—Standard or execute form
  absexp—List form

buffer_area_size is the length in bytes of the area specified in the buffer_area parameter.

Restriction: There is no way to determine, in advance, the exact buffer size required to contain the directory entries on a single request. A formula for length calculation is provided in Figure 1.

 

Figure 1. Buffer size calculation for GET function.

FORMULA:

buffer_area_size = L'DESB_FIXED + (input_list_entry_count * (SMDE_MAXLEN + gap_size))

WHERE:

buffer_area_size

is the storage required to hold input_list_entry_count number of entries.

DESB_FIXED

is the fixed (header) portion of the buffer. It is a constant defined by the IGWDES macro.

SMDE_MAXLEN

is a constant defined by macro IGWSMDE that defines the current maximum size of a single SMDE entry. This is a very large value because names can be up to 1024 bytes in length.

gap_size

is the value specified by the ENTRY_GAP parameter on the GET or GET_ALL function.

input_list_entry_count

is the value passed on the NAME_LIST parameter for the number of entries in the list or 1 if PDSDE is specified.

 

AREAPTR=buffer_area_address  A–type address or (2-12). Standard form  RX–type address or (2-12). Execute form   A–type address. List form

specifies a word where GET, GET_ALL, and GET_NAMES store the address of the first DESB buffer output.

The buffer-area address points to a chain of buffers mapped by the DESB mapping in the IGWDES mapping macro on return from the function.

The subpool number for the storage obtained is placed in the buffer header. See the description of the SUBPOOL keyword for subpool value determination.

It is your responsibility to release the storage using the STORAGE or FREEMAIN macro.

If you issue a DESERV call while running in 24-bit addressing mode, the storage area returned will be below the 16 MB line. If you issue a DESERV call while running in 31-bit addressing mode, the storage returned can be above or below the 16 MB line.

AREAPTR and AREA are mutually exclusive.

BYPASS_LLA={YES | NO}

indicates whether the GET function should bypass LLA's cached directory entries and go only to the current library directory or use LLA's cached directory entries if they are available.

BYPASS_LLA=YES indicates that the LLA cache is not examined. BYPASS_LLA=NO, the default, indicates that the LLA cache is examined before attempting to obtain information directly from the data set.

This is an optional parameter to the GET function.

Currently, the GET_ALL function does not obtain member list from LLA. Therefore, the directory entries come directly from the data set as though BYPASS_LLA=YES were specified.

Tip: Response time is better if the directory entries are obtained from LLA.

CONCAT={concat_number|ALL}

specifies the library concatenation.

concat_number Absexp or (2-12) Standard and execute form. Absexp List form.

specifies for the GET_ALL and GET_NAMES function the specific library in a concatenation of libraries. DESERV returns all the member names. concat_number is a numeric value in the range of 0 to 255.

This is an optional parameter and the default is the first library in the concatenation (that is, 0).

ALL

specifies (for the GET_ALL function only) to return all the names in each PDS or PDSE directory in the concatenation. DESERV returns a list of directory entries which contains a merged list of SMDEs from each data set in the concatenation where duplicate member names have been eliminated.

CONN_ID=connection_addr  A—type address or (2-12). Standard form  RX—type address or (2-12). Execute form  A—type address. List form

specifies the location of the 4-byte value used by the GET, GET_ALL, and RELEASE functions. The four bytes are a token that relates connections to a particular invocation of a function. It may indicate a number of connections or no connections at all.

For the RELEASE function, CONN_ID is an input parameter and is mutually exclusive with DE_LIST.

For the GET and GET_ALL functions, CONN_ID is an output parameter.

CONN_ID is meaningful only when one or more of the designated libraries are PDSEs.

Note: A maximum of 65536 connection identifiers per DCB can exist simultaneously. You can free the identifier by using the RELEASE function and specifying the connection identifier to be freed. The identifier is not freed when using DE_LIST if the CONN_ID parameter was specified on the GET or the GET_ALL functions.

CONN_INTENT={NONE|HOLD}

Specifies the intent of the connection to be used by the GET and GET_ALL functions when a connection is requested.

Intent

Result

NONE

No connection is to be established.

HOLD

Minimal connection to preserve access to the member (or system key/supervisor state only).

This parameter is required by the GET function since a connect intent of NONE is not valid. CONN_INTENT=HOLD must be specified for the GET function.

This parameter is optional and defaults to a connect intent of NONE when used with the GET_ALL function. CONN_INTENT=HOLD for the GET_ALL function requires the caller to be in supervisor state or system key .

CONN_INTENT is meaningful only when one or more of the designated libraries are PDSEs.

DCB=data_control_block

specifies the DCB that identifies the libraries to be used for the particular function. data_control_block is an open data control block.

For the RENAME, DELETE, and UPDATE functions the DCB must be open for OUTPUT or UPDAT. For all other functions the DCB must be open for INPUT, OUTPUT, or UPDAT.

DE_LIST=(input_list,input_list_entry_count)

specifies a list of directory entries that identify connections to members that the RELEASE function is to release. The storage must be addressable in the key of the caller.

input_list   A–type address. Standard form   RX–type address or (2-12). Execute form   A–type address. List form.

input_list specifies a list of entries mapped by the DESL structure.

input_list_entry_count   Absexp or (2-12). Standard or execute form   Absexp. List form

input_list_entry_count contains the number of entries in the list.

For the RELEASE function, DE_LIST is mutually exclusive with CONN_ID.

ENTRY_GAP=({gap_size|0})

specifies space to be reserved by the GET and GET_ALL functions within each buffer entry for use by the caller.

gap_size   Absexp or (2-12). Standard or Execute form   Absexp. List form

gap_size is a numeric value from 0 to 2048.

DESERV places the length specified in the header area of the DESB.

EXT_ATTR={YES | NO}

indicates whether the GET or GET_ALL functions should return the extended attributes in the SMDE. This function is valid only for data member PDSEs.

EXT_ATTR=YES indicates that the returned SMDE will contain the extended attributes, SMDE_EXT_ATTR.

EXT_ATTR=No , the default, indicates that the returned SMDE will not contain the extended attributes.

This is an optional parameter to the GET or the GET_ALL functions.

FUNC={DELETE|GET|GET_ALL|GET_NAMES|RELEASE|RENAME|UPDATE}

specifies the particular function to be performed.

HIDE={YES| NO}

is used for the GET_ALL function to indicate if hidden names are to be visible in the name search. Hidden names are names generated by the program management binder when you specify ALIASES(ALL)

Hidden names are normally used only for program management binding purposes, and are supported only for program objects in PDSE libraries. As a single program object can contain many hidden names and as these names do not represent executable entry points into a module, they are of little interest to end users. Utilities and other programs which list or display member names and aliases typically omit hidden aliases.

YES

DESERV searches for and returns only exposed names (names specified during program management binding).

NO

DESERV searches for and returns all names types.

NO is the default for the HIDE parameter.

MF={L | E,parm_list[,NOCHECK| COMPLETE]| S}

specifies how the macro should generate its code.

L

specifies the list form of the macro. This form generates an inline parameter list, initializes the eye catcher, length, level of parameter, and optionally, sets some static parameters.

E

specifies the execute form of the macro. This form updates a parameter list and transfers control to the service routine.

The third argument, COMPLETE or NOCHECK, is optional. The default is COMPLETE. This argument specifies whether required keyword checking is to be done. If MF=E is coded with the NOCHECK argument, the macro does not check that all required keywords have been specified. If MF=E is coded with the COMPLETE argument (or COMPLETE is allowed to default) the parameter list is cleared to binary zeros (except the header portion, the first 16 (X'10') bytes), and checking is done for all required parameters.

S

specifies the standard form of the macro. This form generates a complete inline expansion of the parameter list, checks for all required and invalid keywords, and invokes the specified function. It should not be used in refreshable or reentrant code sections.

parm_list—RX-type Address or (1-12)

specifies the address of the parameter list. Valid for the MF=E form of the DESERV macro only.

NAME=name_recordA—type address or (2-12). Standard form.RX—type address or (2–12). Execute formA—type address. List form

specifies the member name on the GET_NAMES function. name_record is a varying length byte string of at most 1024 bytes of data. The structure is mapped by the DESN mapping in the IGWDES mapping macro.

name_record specifies either the primary or any of the alias names when used for the GET_NAMES function.

NAME_LIST=(input_list,input_list_entry_count)

is used with the GET, GET_G, GET_ALL_G, DELETE, RENAME, UPDATE functions.

For GET, it defines the names for which directory entries are to be obtained and points to the output directory entries.

For GET_G, it defines a primary name for which generation directory entries are to be obtained. input_list_entry_count must indicate one entry. If the output area is filled before all generation directory entries could be returned, subsequent calls can be made to return additional generation directory entries for the initial primary name. On these subsequent calls, the NAME_LIST should contain the generation name (12-byte SMDE_GENE_NAME) to be used as a continuation point. It can be copied from the last generation directory entry found in the output area returned by the previous call. Input_list_entry_count must indicate one entry.

For GET_ALL_G, NAME_LIST is not required to return generation directory entries for a PDSE. However, if the output area is filled before all generation directory entries could be returned, subsequent calls can be made using NAME_LIST to return additional generation directory entries for the PDSE. On these subsequent calls, the AME_LIST should contain the generation name (12-byte SMDE_GENE_NAME) to be used as a continuation point. It can be copied from the last generation directory entry found in the output area returned by the previous call. Input_list_entry_count must indicate one entry.

For DELETE, it defines the names which are to be deleted. For RENAME, it defines the old names and the new names.

For UPDATE, it defines the directory entries which are to be updated.

NAME_LIST is mutually exclusive with the PDSDE parameter.

input_list
   A–type address or (2-12). Standard form.
   RX-type address or (2–12). Execute form
   A-type addres. List form

input_list specifies a list of entries.

The input_list structure is mapped by the DESL mapping in the IGWDES mapping macro.

input_list_entry_count
   Absexp or (2-12). Standard or execute form.
   Absexp. List form.

input_list_entry_count contains the number of entries in the list.

PDSDE=BLDL_directory_entry  A-type address or (2-12). Standard form  Rx-type address or (2-12). Execute form  A-type address. List form

specifies a BLDL format directory entry to be used by the GET function to obtain a connection to PDSE member. The member locator token (MLT) for a PDSE member, and concatenation number in the directory entry are used to identify the member. If the concatenation number identifies a PDS, the input BLDL directory entry is converted to SMDE format without searching any directories.

PDSDE is mutually exclusive with the NAME_LIST parameter.

Note: The BLDL directory entry must point to the name portion of a BLDL directory entry, not the FF portion. If the BLDL directory entry points to the FF portion, an RC=0 is returned, but the results are incorrect.

RETCODE=return_code  A-type address or (2-12). Standard form  Rx-type address or (2-12). Execute form  A-type address. List form

specifies the name of the variable where the function is to store the return code associated with the result of the function invocation. return_code is a four byte value. Independently of whether you code RETCODE, the return code is returned in register 15.

See DESERV completion codes for valid return code values.

RSNCODE=reason_code  A-type address or (2-12). Standard form  Rx-type address or (2-12). Execute form  A-type address. List form

specifies the name of the variable where the function is to store the reason code associated with the result of the function invocation. The high order two bytes of the reason code contain the component id (x'27') and the module identifier of the module which detected the error. The low order two bytes of the reason code contain the actual reason code values. Independently of whether you code RETCODE, the reason code is returned in register 0.

See Reason codes returned by the DESERV macro for reason code values.

SUBPOOL=subpool_id  Absexp or (2-12). Standard or execute form  Absexp. List form

specifies the subpool identifier to be used by the function when acquiring storage for the buffer. subpool_id is a value from 0 to 255 that is optional on the GET, GET_ALL, and GET_NAMES functions.

The actual key and subpool used to acquire storage are:

• If the subpool is specified and is not a user subpool and the caller is NOT authorized (KEY or STATE) the request is rejected as an error.
• If the subpool is specified and is not a user subpool and the caller is authorized the storage is obtained with the subpool specified and the caller's key. This technique assumes that the subpool/key combination is valid. An error occurs if the combination is invalid.
• If the subpool is specified and is a user subpool the storage is obtained with the subpool specified in task key.
• If the subpool is NOT specified the storage is obtained with the subpool 0 in task key.
• If the subpool specified is 0 and the caller is executing in key 0, the storage returned is in subpool 250.