The Acquire Device using CLF (ACQDEVCLF) command is used by a CL program to acquire a device for a file.

Restrictions:

• This command is valid only within a CL program.
• The file identified by the FILEID parameter must have been previously opened using the Open File using CLF (OPNFCLF) command.
• The file identified by the FILEID parameter must be either a display file or an ICF file.
• The device being acquired must be available.
• This command is not threadsafe.

Parameters

File identifier (FILEID)

Specifies the file identifier that was used on a previous Open File using CLF (OPNFCLF) command in the application.

This parameter is used by CLF commands to identify the file to be processed by the command.

This is a required parameter.

simple-name

Specify a name that matches the FILEID parameter value of a previous OPNFCLF command.

Display or ICF device (DEV)

Specifies the display or ICF device to be acquired by the application. This device is then associated with the file identified by the FILEID parameter. The acquired device becomes the current device for the file.

character-value

Specify the name of the display or ICF device to be acquired.

Error found (ERR)

Specifies a CL logical variable to receive general error status. If the variable value is equal to '1' (true) then an error was found when performing the command. If the variable value is equal to '0' (false) then no error was found when performing the command.

This CL variable can be declared by the Declare Indicators using CLF (DCLINDCLF) command, the Generate Indicators using CLF (GENINDCLF) command, or by you using the Declare CL Variable (DCL) command. The two CLF commands would have specified CLFIND(*YES). When using the CLF commands the name of the CL variable is &ERR.

If no CL variable is specified and an error condition is encountered the application program will be sent an escape message.

logical-value

Specify the name of a CL variable declared as TYPE(*LGL).

Program opening file (OPNPGM)

The same FILEID value can be in use across multiple programs within a job. Each instance of a file open is uniquely identifed by the OPNPGM parameter. This parameter specifes the application program that initially opened the file using the Open File using CLF (OPNFCLF) command.

All CLF commands that reference the same FILEID and OPNPGM combination share the same view of the file. If one program causes the position within the file to change all programs see that change. If one program closes the file then the file is closed to all programs.

The combination of FILEID and OPNPGM must be unique within the activation group the application program is running in.

If the program name is *CURPGM then the library qualifier for this parameter is ignored. The library of the current program will be used.

Single values: Program opening file

*CURPGM

The current program opened the file associated with FILEID. It is this file open instance that is to be used.

Qualifier 1: Program opening file

name

Specify the name of the program that initially opened the file identified by FILEID. It is this file open instance that is to be used.

Qualifier 2: Library

*CURLIB

The current library for the thread is used. If there is no current library for the thread then library QGPL is used.

name

Specify the name of the library where the program that initially opened the file is located.

Examples for ACQDEVCLF

Example 1: Acquire a Display Device

    AcqDevCLF  FileID(VC2EMPDSP1) Dev('XYZ')

This command acquires the display device named 'XYZ' and associates the device with the VC2EMPDSP1 display file. The display device must be at the Sign On panel.

Example 2: Acquire a Display Device for Employee Master Maintenance

    Pgm
    /******************************************************/
    /* The device to be acquired is identified by         */
    /* variable &DEVICE and has a name of 'D'             */
    /******************************************************/
    Dcl        Var(&Device) Type(*Char) Len(10) Value(D)
    /******************************************************/
    /* Declare the Employee master file VC2EMP, display   */
    /* file VC2EMPDSP1, and indicators associated with    */
    /* CLF Input/Output commands                          */
    /******************************************************/
    DclFCLF    FileID(VC2EMP)
    DclFCLF    FileID(VC2EMPDSP1)
    DclIndCLF  CLFInd(*Yes)
    /******************************************************/
    /* Open the two files.  Note that the display file    */
    /* VC2EMPDSP1 has been created using MAXDEV(2)        */
    /******************************************************/
    OpnFCLF    FileID(VC2EMP) Usage(*Both) AccMth(*Key)
    OpnFCLF    FileID(VC2EMPDSP1) Usage(*Both)
    /******************************************************/
    /* Acquire the device identified by &DEVICE.          */
    /* Acquiring the device also makes the device the     */
    /* current device. Input/Output operations to a file  */
    /* will be done using the current device.             */
    /******************************************************/
    AcqDevCLF  FileID(VC2EMPDSP1) Dev(&Device)
    /******************************************************/
    /* Enter a DOWHILE loop that is exited when command   */
    /* key 3 is pressed.                                  */
    /*                                                    */
    /* Within the loop:                                   */
    /* 1 Write and read to the current display device (D) */
    /*   of the VC2EMPDSP1 *DSPF record format PROMPT.    */
    /*   PROMPT asks for an employee number. A valid      */
    /*   employee number would be 1. The user can press   */
    /*   ENTER or command key 3.                          */
    /* 2 If command key 3 was pressed leave the DoWhile   */
    /*   loop                                             */
    /* 3 Otherwise readthe employee record for the        */
    /*   employee number entered.                         */
    /* 4 If no record is found (&RNF is '1') a message is */
    /*   displayed based on &IN50                         */
    /* 5 If a record is found record format CHANGE is     */
    /*   written to and read from the current device.     */
    /*   CHANGE allows the user to change employee        */
    /*   information (ENTER), delete the employee (F23),  */
    /*   return to PROMPT without updating the employee   */
    /*   record (F12), or exit the application (F3).      */
    /* 6 The user is then returned to the PROMPT display  */
    /*   to enter the next employee number                */
    /******************************************************/
    DoWhile    Cond(*Not &IN03)
               WrtReadCLF RcdFmt(PROMPT)
               If Cond(&IN03) Then(Leave)
               ReadRcdCLF FileID(VC2EMP) Type(*Key) +
                 RcdNotFnd(&RNF) KeyRel(*EQ) +
                 KeyList(&EmpNbr)
               If Cond(&RNF) Then(Do)
                  ChgVar Var(&IN50) Value('1')
                  Iterate
                  EndDo
               WrtReadCLF RcdFmt(CHANGE)
               Select
                  When Cond(&IN03) Then(Leave)
                  When Cond(&IN12) Then(Do)
                       RlsRcdCLF VC2EMP
                       Iterate
                       EndDo
                  When Cond(&IN23) Then(DltRcdCLF VC2EMP)
                  OtherWise Cmd(UpdRcdCLF FileID(VC2EMP))
                  EndSelect
               EndDo
    /***********************************************/
    /* When F3 is used to exit the DoWhile loop    */
    /* close the files and return                  */
    /***********************************************/
    CloFCLF    FileID(VC2EMP)
    CloFCLF    FileID(VC2EMPDSP1)
    EndPgm

This example acquires the display device named 'D' and then allows a user at the device to maintain employee records. When the program ends device 'D' returns to the Sign On panel.

The source for the example can be found in member DEV_EMPUA of source file VC2CLSRC in library VC2CLF. The source for physical file VC2EMP can be found in member VC2EMP of source file QDDSSRC in library VC2CLF. The source for display file VC2EMPDSP1 can be found in member VC2EMPDSP1 of source file QDDSSRC in library VC2CLF.

All of the referenced objects should currently exist in library VC2CLF. To create DEV_EMPUA into QTEMP you can use the commands

    AddLibLE Lib(VC2CLF)
    CrtBndCLF Pgm(QTEMP/DEV_EMPUA) SrcFile(VC2CLSRC)

Error messages for ACQDEVCLF

*ESCAPE Messages

VC2502E

File ID &1 is not open.

VC25049

Acquire operation of device &2 to file ID &1 not successful.

VC29002

Function did not complete. See previously listed messages related to possible user errors.

VC29003

Function did not complete. See previously listed messages for possible cause.

VC29004

Function did not complete. See previously listed messages for possible cause.

VC29005

Function did not complete. Contact your service provider.