DESERV MF=L is the list form of the DESERV macro.
- 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 function stores 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.
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, 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 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.