Open STATEMENT

PURPOSE: The OPEN statement accesses an auxiliary DS that has been declared with the DEFER OPEN option in the RELATE statement. The CLOSE statement closes access to an auxiliary DS that has been opened. The OPEN and CLOSE statements make it possible to access a DS at some point during the execution of a PM, yet make the DS available to other users during the rest of the PM execution.

In some applications the name of the DS or DI is not known when the PM begins execution. If the DEFER OPEN option is specified in the RELATE statement, the name of the DS or DI can be specified later in the OPEN statement. Also, multiple DS file can be processed with one "related" DS by CLOSEing one and then OPENing another.

For example, a PM can be created where the user enters the DS name or DI name during PM execution. The PM can ask the user the name at any time prior to the OPEN statement.

The current DS or DI can also be CLOSEd and another OPENed, thus allowing many DS’s or DI’s to be processed with one designator.

SYNTAX

OPEN \\designator\\ [WITH str_exp] [HUSH] [IF; UNLESS]

designator	is the designator specified in the RELATE statement in the CONTROL section.
str_exp	is a quoted literal, a character or alphabetic field, a function, or a concatenation of any of the preceding that evaluates to a valid DI name or DS name. Only DS and DI names may be used in the OPEN statement.

Example

CONTROL SECTION

   RELATE DI MAIN AS MASTER FOR UPDATE
   RELATE DS FLAG AS FLAG FOR UPDATE DEFER OPEN
   RELATE SF BOOK_REP AS REPORT 1
   !
INITIAL SECTION
   OPEN FLAG
   GET FROM FLAG FIRST RECORD
   IF FLAGIT = "FREE"
      "BUSY" TO FLAGIT
      PUT RECORD IN FLAG
      CLOSE FLAG
   ELSE
      TYPE "MAIN IS BUSY. TRY LATER"
      EXIT PROCESS
   CONTINUE
FINAL SECTION
   OPEN FLAG
   GET FROM FLAG FIRST RECORD
   "FREE" TO FLAGIT
   PUT RECORD IN FLAG
   CLOSE FLAG

The RELATE statement can specify the name of a SD, ID, DS, or DI. The valid combinations of SD and ID are shown in the table below.

Valid Object Type Combinations:

RELATE SD --> OPEN DS
RELATE ID --> OPEN DI

For a RELATEd SD, the name of any DS that was created with the SD can be specified in str_exp in the OPEN statement.

RELATE SD INVOICES AS abc FOR INPUT DEFER OPEN
:
OPEN abc WITH YTD_INVOICES! (name of a DS)

For a RELATEd ID, the name of any DI that was created with the ID can be specified in str_exp in the OPEN statement.

RELATE ID INV_ID AS abc FOR UPDATE DEFER OPEN
:
OPEN abc WITH YTD_INV! (name of a DI)

For a DS, the name specified in str_exp in the OPEN statement can be different from that specified in the RELATE statement. The SD of the DS specified by str_exp must be the same SD of the DS specified in the RELATE statement. If they do not match, the system field @AUX will be set to “OPEN” and an error message displayed.

RELATE DS YTP_INV AS abc FOR UPDATE DEFER OPEN
:
OPEN abc WITH FEB_INV! (name of a DS)

For a RELATEd DI, the name specified in str_exp in the OPEN statement can be different from that specified in the RELATE statement. The ID that created the DI specified by str_exp must be the same ID associated to the DI specified in the RELATE statement. If they do not match, the system field @AUX will be set to “OPEN” and an error message is displayed.

NOTES: The OPEN statement must precede the first access of the auxiliary DS. The DS then remains open until the CLOSE statement occurs or the PM terminates.

An example of a possible use of this feature would be where there are data sets for each month and you don’t know which is to be used until run time where you must ask the user which month they wish to process. Then the appropriate months data set can be opened for processing.

Also, a data set can be created with a logical name in the PM and the program can define the logical based on the name of the file you wish to process. For example

DEFINE PM PRT.REP

!===============

CONTROL SECTION

!==============

RELATE DS PRTFILE:  AS REP FOR INPUT DEFER OPEN

!==============

DECLARE SECTION

!==============

CNT,I, MAX

!==============

DETAIL SECTION

!==============

TYPE ‘Enter the name of the file to be printed:
‘, NOCR ACCEPT @STRING(1)

@DEFINE.LOGICAL(‘PRTFILE’, @STRING(1)) TO @STRING(2)

IF @STRING(2) = ‘YES’

   OPEN REP

   IF:10 @AUX = ‘YES’

   0 TO CNT

      START:20

      GET FROM REP NEXT RECORD HUSH

      LEAVE:20 IF @AUX # ‘YES’

      TYPE TEXT@’’

      REPEAT:20

   ELSE:10

   TYPE ‘Cannot open the file, operation aborted.’ ,@cr

   continue:10

ELSE

TYPE ‘Invalid file name, operation aborted.’, @CR

CONTINUE

If the OPEN is successful, @AUX will be set to “YES.” If the OPEN is not successful, @AUX is set to “OPEN” and an error message is displayed. The error message can be turned off with a HUSH clause.

If a DI is not formed when the OPEN statement is executed, @AUX will be set to “OPEN” and an error message will be displayed.

If opening a DS or DI associated with a designator that already has a DS or DI open, an error message will be displayed and @AUX will be set to “OPEN.”

SEE ALSO: CLOSE and RELATE Statement