The IDENTIFY service

To select the data-in-virtual object that you want to process, use IDENTIFY. IDENTIFY has the following required parameters:

ID, TYPE, and DDNAME if TYPE=DA, or
STOKEN if TYPE=HS.

IDENTIFY has two optional parameters: CHECKING and TTOKEN. Only programs running in supervisor state or under a PSW key of 0-7, or both, can use the CHECKING and TTOKEN parameters.

The following examples show two ways to code the IDENTIFY service.

Hiperspace™ object:

DIV IDENTIFY,ID=DIVOBJID,TYPE=HS,STOKEN=HSSTOK

Data set object:

DIV IDENTIFY,ID=DIVOBJID,TYPE=DA,DDNAME=DDAREA

ID: The ID parameter specifies the address where the IDENTIFY service returns a unique eight-byte name that connects a particular user with a particular object. This name is an output value from IDENTIFY, and it is also a required input value to all other services.

Simultaneous requests for different processing activities against the same data-in-virtual object can originate from different tasks or from different routines within the same task or the same routine. Each task or routine requesting processing activity against the object must first invoke the identify service. To correlate the various DIV macro invocations and processing activities, the eight-byte IDs generated by IDENTIFY are sufficiently unique to reflect the individuality of the IDENTIFY request, yet they all reflect the same data-in-virtual object.

TYPE: The TYPE parameter indicates the type of data-in-virtual object, either a linear data set (TYPE=DA) or a hiperspace (TYPE=HS). DIV does not support VSAM extended format linear data sets for use as a DIV object for which the size is greater than 4GB.

DDNAME: When you specify TYPE=DA for a data set object, you must specify DDNAME to identify your data-in-virtual object. If you specify TYPE=HS with IDENTIFY, do not specify DDNAME. (Specify STOKEN instead.) Do not specify a DDNAME that corresponds to a VSAM extended format linear data set for which the size is greater than 4GB, because DIV does not support them for use as a DIV object.

STOKEN: When you specify TYPE=HS for a hiperspace object, you must specify STOKEN to identify the hiperspace that is your data-in-virtual object. The STOKEN must be addressable in your primary address space. The hiperspace must be a standard hiperspace and must be owned by the task issuing the IDENTIFY. The system does not verify the STOKEN until your application uses the associated ID to access the object.

CHECKING: The CHECKING parameter enables you to request or bypass data-in-virtual validity checking. If you bypass validity checking, (CHECKING=NO), all data-in-virtual services bypass validity checking for the corresponding ID. You then have to ensure that the parameters and the environment are valid each time a data-in-virtual service is invoked. A parameter or environment that is not valid causes unpredictable results. The default is to allow data-in-virtual to perform validity checking. Bypass validity checking only if you need to improve data-in-virtual performance.

TTOKEN: To assign ownership of the corresponding ID to another TCB, code the TTOKEN parameter. You can assign the ID only to a TCB that is in the same TCB chain as your program, but is higher in the chain.