LMINIT—generate a data ID for a data set

The LMINIT service allows the dialog to associate a data ID with a specified ISPF library, concatenation of ISPF libraries or MVS™ partitioned data sets, or an MVS partitioned or sequential data set. The data ID is generated by LMINIT and can be used to identify the data set for processing by other library access services or the BROWSE or EDIT service. If the specified data set exists but has not been allocated, the LMINIT service allocates the data set. If two or more existing ISPF libraries are specified, the LMINIT service concatenates the libraries.

Note: The LMINIT service does not support data sets created by a method that does not set the format one DSCB field (DS1DSORG).

The input to the LMINIT service defines the physical and logical characteristics of the data set. This simplifies the invocation of the other library access services by supplying the information needed to invoke the service for a given data set. For instance, the dialog supplies the information required by the input fields on the ISPF View Entry Panel to LMINIT. Later invocations of the BROWSE service with that data set are made much simpler by using the data ID generated by the LMINIT service.

The LMINIT service must be completed before LMOPEN can be used. Otherwise, the data set cannot be opened for processing. If LMINIT is issued with an enqueue (ENQ) of SHRW and LMOPEN is issued with the OUTPUT option, it is essential that an LMCLOSE is issued when the dialog has finished processing the data set, since the DASD volume is reserved until LMCLOSE is invoked.

You can use the LMQUERY service to find out how the LMINIT parameters are set.

For each LMINIT invocation, you should invoke a matching LMFREE service. The LMFREE service removes the data ID generated by LMINIT. Invoke the LMFREE service when the data ID is no longer needed. Otherwise, the ISPF library or data set associated with the data ID is not released until ISPF terminates.

If you modify the data sets associated with a data ID, then you must invoke the LMFREE and LMINIT services for the data ID before processing the data sets with another service. Failure to update the directory blocks associated with the data ID may cause I/O errors.

For example, if you use a service like LMCOPY or LMMOVE to modify a data ID that was defined by the LMINIT service, and the modified resource is needed for other services, then the data ID that references the modified resource must first be freed with LMFREE, then re-allocated with LMINIT. In more specific terms, say you perform an LMMOVE operation to move data from DATA-ID(A) to DATA-ID(B). Then you immediately use the LMMOVE service to move data from DATA-ID(B) to DATA-ID(C). The second operation (from B to C) might result in an I/O error. To correctly complete this task, make all updates to DATA-ID(B), free DATA-ID(B) with the LMFREE service, then use the LMINIT service for DATA-ID(B) so that the changes made to DATA-ID(B) can be referenced by other services. Any time this initialization is not done on a modified resource and references to that resource are made, an I/O error might occur.

Command invocation format


>>-ISPEXEC--LMINIT--DATAID(data-id-var)------------------------->

>--+-| PROJECT options |-+--+----------------+------------------>
   +-DATASET(dsname)-----+  '-VOLUME(serial)-'   
   '-DDNAME(ddname)------'                       

>--+--------------------+--+------------------+----------------->
   '-PASSWORD(password)-'  |      .-SHR---.   |   
                           '-ENQ(-+-EXCLU-+-)-'   
                                  +-SHRW--+       
                                  '-MOD---'       

>--+--------------+--------------------------------------------><
   '-ORG(org-var)-'   

PROJECT options

|--PROJECT(project)--GROUP1(group1)--TYPE(type)----------------->

>--+----------------+--+----------------+--+----------------+---|
   '-GROUP2(group2)-'  '-GROUP3(group3)-'  '-GROUP4(group4)-'

Call invocation format


>>-CALL--ISPLINK--('LMINITbb'--,--data-id-var------------------->

>--+-,project,group1--,-+-group2-+--,-+-group3-+--,-+-group4-+--,type-+-->
   |                    '-'b'----'    '-'b'----'    '-'b'----'        |   
   +-,dsname----------------------------------------------------------+   
   '-,ddname----------------------------------------------------------'   

                                   .-'SHRbbbbb'-.   
>--,-+-serial-+--,-+-password-+--,-+-'b'--------+--------------->
     '-'b'----'    '-'b'------'    +-'EXCLUbbb'-+   
                                   +-'SHRWbbbb'-+   
                                   '-'MODbbbbb'-'   

>--,-+-org-var-+-);--------------------------------------------><
     '-'b'-----'


>>-CALL--ISPEXEC--(buf-len,buffer);----------------------------><

You must specify the data set (ISPF library, or MVS partitioned or sequential data set) as a ddname, a dsname, or a three-level qualified name. The search sequence LMINIT uses is ddname, then dsname, then the three-level qualified name. If LMINIT finds the name it is looking for, it uses that name. Otherwise, it looks for the next type of name in the sequence. If there is no three-level qualified name, LMINIT issues an error message.

Parameters

data-id-var

The name of the variable that will store the data ID to be associated with the data set. The LMINIT service always generates a unique data ID. The data ID is an input parameter to most of the other library access services, and optionally to the BROWSE and EDIT services, but is an output parameter from the LMINIT service. The data ID length is 8 characters. Therefore, the maximum length of this parameter is 8 characters.

To invoke the service, you must specify the data ID variable name and an ISPF library name (project, group, and type), a dsname, or a ddname.

In the LMINIT service, data-id-var is the name of the variable that holds the data ID (for example, DATAID(DDVAR)). When you use the data ID keyword with other services, you must pass the value of the variable (for example, DATAID(&DDVAR)). The Library search order is from the lowest (group1) to the highest (group4). The search for a member stops when the first matching member name is located.

project

The highest-level qualifier in the specification of an ISPF library or MVS three-level qualified data set. This parameter is required if neither the dsname nor the ddname parameter is specified. The maximum length of this parameter is 8 characters.

group1

The second-level qualifier in the specification of an ISPF library or MVS three-level qualified data set. This parameter is required if neither the dsname nor ddname parameter is specified. The maximum length of this parameter is 8 characters.

group2

Continues the second-level qualifier. It is not required, but if present it represents an ISPF library in a concatenation sequence. The maximum length of this parameter is 8 characters.

group3

Continues the second-level qualifier. It is not required, but if present it represents an ISPF library in a concatenation sequence. The maximum length of this parameter is 8 characters.

group4

Continues the second-level qualifier above. It is not required, but if present it represents an ISPF library in a concatenation sequence. The maximum length of this parameter is 8 characters.

type

The third-level qualifier in the specification of an ISPF library or MVS three-level qualified data set. This parameter is required if neither the dsname nor the ddname parameter is specified. The maximum length of this parameter is 8 characters.

dsname

The name of an existing MVS partitioned or sequential data set. A member name or pattern cannot be included in the dsname of a partitioned data set. The maximum length of this parameter is:

For fully qualified data sets, 46 characters, with 2 characters for a beginning and ending single quotation mark, and 44 characters for the data set name.
If the single quotation marks are omitted, the user's data set prefix from the TSO profile is automatically appended to the front of the data set name. The length of the data set name specified plus the length of the TSO prefix and the separator "." must not exceed 44 characters.

ddname

The data set definition name of a data set that is already allocated to the TSO user before invocation of the LMINIT service. This can be done by using the TSO ALLOCATE command or MVS job control language (JCL). The data set must be either partitioned or sequential.

If the ddname is allocated to one or more partitioned data sets, member names cannot be included. LMINIT allows up to 16 concatenated data sets.

Note: If the ddname is allocated to a multivolume data set, LMINIT is not supported. Do not try to LMINIT a multivolume data set by ddname.

Sequential data sets must be allocated as either OLD, SHR, NEW, or MOD. If the ddname is allocated as NEW, the record format, data set organization, record length, and block size must be specified when the ddname is allocated. For a partitioned data set, the number of directory blocks must also be specified when the ddname is allocated. The maximum length of this parameter is 8 characters.

serial

The serial number of the DASD volume on which the data set resides. This parameter is associated with the dsname parameter, but is required only if the data set is not cataloged. The maximum length of this parameter is 6 characters. Volume serial is associated with the dsname parameter and will be ignored when the dsname is not entered.

password

The MVS password of the data set. This parameter is required only if the data is password-protected. If the password is invalid, it is detected by the LMOPEN service (see LMOPEN—open a data set). Do not specify a password for RACF-protected data sets. The maximum length of this parameter is 8 characters.

SHR|EXCLU|SHRW|MOD

The requirements for enqueuing (ENQ) the data within ISPF so that the dialog can use it in the desired manner. This parameter is ignored if the ddname parameter is specified.

SHR shows that the existing data can be shared; for example, it can be used by two or more users who want only to read the data. You can specify this option when using the INPUT option of the LMOPEN service. SHR is the default.

EXCLU shows that exclusive use of the data is required; for example, when you want to change the data no one else can have access to it. You can specify this option for either the INPUT or OUTPUT option of the LMOPEN service.

SHRW permits a shared write for the data. This option is used by ISPF Edit. It is used only for a partitioned data set. In this way, more than one user can read from the data, but members can be rewritten when necessary through an enqueue or dequeue used by Edit. Edit can now have the data ID open for INPUT and OUTPUT at the same time. A data set that is allocated with an enqueue of SHRW can be opened for either INPUT or OUTPUT using the LMOPEN service.

MOD shows that more records are to be added to the end of a sequential data set. MOD is used with the OUTPUT option of the LMOPEN service.

org-var

The name of the variable into which the organization of the data is stored. The variable contains "PO" if the data set is partitioned or "PS" if it is physical sequential. If you specify a concatenated set of ISPF libraries, the organization of the first group of the concatenated libraries is returned. The maximum length of this parameter is 8 characters.

buf-len

A fullword fixed binary integer containing the length of the buffer parameter.

buffer

A buffer containing the name of the service and its parameters in the same form as they would appear in an ISPEXEC invocation for a command invocation.

Return codes

These return codes are possible:

0: Normal completion.
8: Data ID not created; the error condition is described in System variables used to format error messages.
12: The parameter value is invalid.
16: Truncation or translation error in accessing dialog variables.
20: Severe error; unable to continue.
See System variables used to format error messages for more information about dialog variables.

Note: Data sets allocated with an XTIOT will return a "DDNAME Not Found" message and set RC=8 if XTIOT support is not fully enabled.

Examples

Here are some examples of the LMINIT service:

Example 1:

This example invokes the LMINIT service to associate a data ID with data concatenated from these ISPF libraries:

ISPF.TESTLIB1.PLIOPT
ISPF.TESTLIB2.PLIOPT
ISPF.TESTLIB3.PLIOPT
ISPF.TESTLIB4.PLIOPT

Store the generated data ID in variable DDVAR.

Command invocation

ISPEXEC LMINIT DATAID(DDVAR) PROJECT(ISPF)  +
               GROUP1(TESTLIB1)  +
               GROUP2(TESTLIB2) GROUP3(TESTLIB3)   +
               GROUP4(TESTLIB4) TYPE(PLIOPT)

Call invocation

DCL DDVAR CHAR (8);
CALL ISPLINK('VDEFINE ','DDVAR ',DDVAR,'CHAR    ',
              LENGTH(DDVAR));
CALL ISPLINK('LMINIT  ','DDVAR ','ISPF ',
             'TESTLIB1 ','TESTLIB2 ',
             'TESTLIB3 ','TESTLIB4 ','PLIOPT ');
OR

Set the program variable BUFFER to contain:

BUFFER = 'LMINIT DATAID(DDVAR) PROJECT(ISPF) GROUP1(TESTLIB1)
                GROUP2(TESTLIB2) GROUP3(TESTLIB3)
                GROUP4(TESTLIB4) TYPE(PLIOPT)';

Set the program variable BUFLEN to the length of the variable BUFFER. Issue the command:

CALL ISPEXEC (BUFLEN, BUFFER);

Example 2:

The example shown in Command invocation invokes the LMINIT service for a two-level dsname called SMITH.CLIST, using dsname.

Command invocation

ISPEXEC LMINIT DATAID(DDVAR)               +
               DATASET('SMITH.CLIST')      +
               ENQ(SHR)

Call invocation

CALL ISPLINK('LMINIT  ','DDVAR ',
             ' ',' ',' ',' ',' ',' ',
             'SMITH.CLIST',' ',
             ' ',' ','SHR     ');

Example 3:

The example shown in Command invocation invokes the LMINIT service for a new data set, using ddname.

Command invocation

ATTRIB MYLIST BLKSIZE(800)     +
       LRECL(80) RECFM(F B)    +
       DSORG(PS)
ALLOC DDNAME(MYDD) NEW         +
       SPACE(1,1) TRACKS KEEP  +
       USING(MYLIST)
ISPEXEC LMINIT DATAID(DDVAR) DDNAME(MYDD)

Call invocation

For this invocation, assume DDNAME(MYDD) has been allocated to the user using JCL.

CALL ISPLINK ('LMINIT  ','DDVAR ',
              ' ',' ',' ',' ',' ',' ',
              ' ','MYDD ');