OPEN (AFILE)

ANSI

 

A file must be created or opened prior to any attempt to process data against it. The OPEN instruction initializes an existing file for later access by the program.

 

(1)

[label]

OPEN

{afile},{name}[,{wildcards},{mode}:

 

 

 

{lock},{unlock},{wait},VIEW={viewstring}:

 

 

 

{CANCELCHAR={cancelchar},CHECKTIME={checktime}]:

{ISICACHE={cachesize}

(2)

[label]

OPEN

{afile},{name|tcpip id:port}[,{wildcards}:

 

 

 

{mode},{lock},{unlock},{wait},VIEW={viewstring}:

 

 

 

{CANCELCHAR={cancelchar},CHECKTIME={checktime}]

 

Where:

label

Optional. A Program Execution Label.

afile

Required. A previously defined AFILE variable that is opened.

name

Required. A previously defined Character String Variable or Literal containing the file name to open.

tcpip id:port

Required. A previously defined Character String Variable or Literal containing the IP address and port number of the server executing the Data Manager.

wildcards

Optional. A previously defined Character String Variable or Literal containing the wildcard characters for READ instructions.

mode

Optional. A File Access Mode parameter defining the OPEN mode.

lock

Optional. A Record Locking Mode from the table below defining the record locking strategy.

unlock

Optional. A Record Unlocking Mode from the table below defining the record unlocking strategy.

wait

Optional. A Record Locking Wait Option from the table below defining the locked record wait strategy.

viewstring

Optional. A previously defined Character String Variable or Literal containing the view schema name that is found in database.

cancelchar

Optional. A previously defined Character String Variable or Literal defining the read cancel key. (9.6)

checktime

Optional. A previously defined Numeric Variable or Literal defining the read cancel key check interval. (9.6)

cachesize

Optional. A previously defined Numeric Variable or Literal defining the ISI cache value. (9.6C)

Flags Affected: NONE

Note the following:

  1. If a character string variable is specified for {name}, only the Logical String is used. If a literal is specified, the entire literal string, within the operating system's limitations, is used.

  2. Which, if any, extension is assumed is as follows:

    3.  

    Compiler

    Action

    SUNDB86x

    If the file name is terminated with a period (.), no extension is assumed. Otherwise, the extension AAM is assumed.

    PLBCMP

    The current screen definition file determines whether an extension is required or not. If not and the file name is terminated with the `Filename to extension delimiting character' in the screen definition file, no extension is assumed. Otherwise, the AAM file extension specified in the screen definition file is assumed.

 

  1. If a specific drive and/or directory path is not provided, the current directory is checked for the file. If unsuccessful, any Logged On Drives are searched in ascending order for the file. The Logged On Drives are as follows:

    2.  

    Compiler

    Action

    SUNDB86x

    The drives that have been set to Yes in the screen definition file through the SETDRIVE utility are searched. If not found, the directories that have been set in the PLB_PATH environment variable are searched.

    PLBCMP

    The directories that have been established in the PLB_PATH environment variable or SEARCHPATH instruction are searched.

 

  1. A Datapoint style filename of `filename/ext:drv' is converted to a Sunbelt format as follows:

    2.  

  2. If a file name starts with a dollar sign ($), it is scanned to the first file path or name delimiter. That string is then appended to 'PLBENV_' and the environment table or program information file (ini) is searched for a matching entry. If a matching entry is found, the string associated with the entry is substituted within the file name. An entire file name or path name may be substituted in this manner. For example, if the UET has an entry defined as

    PLBENV_ARDATA=\\server2\acct\ar

    OPEN AFILE,"$ARDATA\company1.aam"

    The actual file is opened as '\\server2\acct\ar\company1.aam'. 

  3. For PLBCMP GUI, if a null file name is used, the standard open dialog is displayed to allow the user to select the appropriate file.

  4. Otherwise, the file name (including drive and/or path designation) must be in the valid operating system format and in the correct case for case sensitive systems like Linux:

    OPEN AFILE,"B:FILENAME" (MS-DOS)
    OPEN AFILE,"/usr/file/fname" (Linux)

    5.  

  5. Format (2) above includes the location of data manager. The {tcpip id} string can be provided in two formats:

  6. {port} is a number that identifies the basic process performed at server IP address. When {port} is not specified, the default port number used is 3934. The 3934 port number has been assigned as a registered user port number by IANA (Internet Assigned Numbers Authority). Care should be taken in selecting a port number to insure that a conflict with pre-assigned numbers does not occur. Please refer to RFC1700 documentation on the internet for port assignment information. The {port} number specified must be the same as specified for the Data Manager task executing at the server.

  7. File names that are in excess of operating system allowances are truncated to meet those standards.

  8. AIMDEX Files resident on a Datapoint RMSRAS server may be opened.

  9. Attempting to OPEN a file that does not exist or using a mode (SHARE, SHARENF, EXCLUSIVE, and READ) that is incompatible with the privileges set for the file or with a mode the file is already open in, results in a trappable I/O error (see TRAP).

  10. If specified, {wildcards} are the wildcard characters for AFILE READ instructions. If not specified, the wildcard character used is the one written when the key file was created. If {wildcards} is a character string variable, only the Form Pointed character is used. If it is a literal, the first literal character is used.

  11. The optional {mode} parameter must be the last parameter on the instruction.

  12. The {mode} may be a keyword or a decimal number or Numeric Variable as follows:

  13. The {mode} keyword option expands functionality and makes OPEN or PREP instructions more dynamic for a user program. When the mode bit definitions specifies an EOR type, this EOR type overrides a type specified by a FORMAT keyword on a AFILE/FILE/IFILE variable declaration. In addition, the inclusion of an EOR type in the MODE causes the runtime to verify that the EOR type of a pre-existing file is the same as required by the MODE settings for all cases except when FORMAT=BINARY is specified in the file declaration. An error occurs if this EOR verification fails.

  14. If the same File Definition Label ({afile}) is specified in a second open or prepare instruction within the same program, the currently open file is CLOSEd before an attempt is made to initialize the new file.

  15. The name of the physical text file is retrieved from the file. If a specific drive or path was not incorporated as part of the physical text file name when the AAM key file was created, a search of all the Logged On Drives is made for the physical text file using the guidelines previously explained.

  16. The maximum key and record lengths are also retrieved from the {name} file. However, the sector size declared in UDA (BUFFER/FIX/FIXED parameter) must be equal to or greater than, the maximum record length retrieved or an I/O error occurs (I47).

  17. Each AFILE requires two operating system file handles (one for the text file and one for the AAM key file). However, the maximum number of files that may be opened concurrently is also limited to those restrictions imposed by the environment in use.

  18. If a FILEPI is active and {name} is null causing activation of the file dialog, the FILEPI is terminated.

  19. The {lock} parameter must be one of the following record locking modes:

    20.  

    Keyword

    Specifies that ...

    LOCKMANUAL

    only READ statements with the 'LK' suffix are to invoke record locking.

    LOCKAUTO

    all READ statements invoke record locking for the file.

 

  1. The {unlock} parameter must be one of the following record unlocking modes:

    2.  

    Keyword

    Specifies that ...

    SINGLE

    any locked record is automatically unlocked before a new record is locked by a READ instruction. This insures that only one record is locked at any given time for a file.

    MULTIPLE

    every record read for the file will lock the record. Records are unlocked only with the UNLOCK statement or when the file is closed.

 

  1. The {wait} parameter must be one of the following record locking wait options:

    2.  

    Keyword

    Specifies that the READ(LK) statements will...

    NOWAIT

    not wait for a record that is locked by some other program. The LESS flag is set.

    WAIT

    wait indefinitely to lock the record.

    WAIT=nn

    wait a specified number of seconds to lock the record. If the record cannot be locked within the specified time limit, the LESS flag is set.

 

  1. Record Locking is not available when using the PLBCE runtime.

  2. The {viewstring} data can be formatted to access various view schema information from a specific database (9.4). The following defines supported data formats for the {viewstring} data:

    VIEW="viewname"

    3. In this case, the 'viewname' is a name that has been inserted into the 'sun_views' table that exists in the default schema database currently being used for a runtime. The default schema database for the runtime is established when the runtime initially loads. The PLB_SCHEMA keyword for the runtime initially establishes a schema database that is used as the default schema database. If the PLB_SCHEMA runtime keyword is not used, a default schema database named 'sunschema.db' is used in the same directory where the runtime executable is located.

     

    VIEW="schemaname.viewname"

    In this case, the 'schemaname' is a name that must exist in the 'sun_databases' table found in the default schema database currently being used for a runtime. When the 'schemaname' is found in the 'sun_databases' table, the final schema database file can be loaded and used to find the specified viewname definitions to be used for the file being opened.

     

    VIEW="viewname|ipaddr"

    In this case, the 'viewname' is a name that has been inserted into the 'sun_views' table that exists in the default schema database currently being used for a Data Manager that has a TCPIP/URL address specified as the 'ipaddr'. The 'ipaddr' can be a URL or a TCPIP:PORT address.

     

    VIEW="schemaname.viewname|ipaddr"

    In this case, the 'schemaname' is a name that must exist in the 'sun_databases' table found in the default schema database currently being used for a Data Manager. The 'ipaddr' can be a URL or a TCPIP:PORT address where the Data Manager can be accessed. The schema database accessed using the 'schemaname' at the Data Manager must exist at the server where the Data Manager is executing.

  3. Before a view can be used in an OPEN instruction, the view schema data must already exist in the schema database. The SCHEMA instruction with the IMPORT keyword also loads the view data into a schema database.

  4. The {cancelchar} value specifies the cancel character or key that aborts a READ operation (9.6A). If the {cancelchar} is a null variable or literal, the cancel support is disabled for this variable. If this keyword is not specified, the cancel character feature is determined by the current program/runtime default settings. This value can be specified as a single key for a character or a key name. The following key names are supported:

    5.  

    ESC, ESCAPE

    F1, F2, F3, F4, F5, F6, F7, F8, F9, F10

    F11, F12, F13, F14, F15, F16, F17, F18, F19, F20

    F21, F22, F23, F24, F25, F26, F27, F28, F29, F30

    F31, F32, F33, F34, F35, F36, F37, F38, F39, F40

    UP,DOWN, LEFT, RIGHT

    INS, INSERT, DEL, DELETE

    HOME, PGUP, PAGEUP.PGDN, PAGEDOWN, END

     

  5. The {checktime} value specifies the elapsed time in seconds used when checking for abort key (9.6A). The value must be in the range of zero (0) to thirty seconds. If a value greater than thirty is specified, thirty is used. If this keyword is not specified, the cancel character feature is determined by the current program/runtime default settings.

  6. The {cachesize} keyword overrides the current runtime ISI caching default setting. By default the PLB runtimes enable ISI caching with the cached sector count set to fifty percent (50%) of the maximum count allowed. The maximum allowed count is two hundred (200) sectors. The {nvardunum} value can be specified from 0 to 200. A value of zero disables the ISI caching. (9.6C),

  7. When a file variable is opened using a Linux OS PL/B runtime, the current SETMODE *LINUXREADLOCK={0|1} value determines whether Linux OS read locks may be used for PL/B read statements using this file variable opened for record locking. Also, note that the Linux OS read locks are only allowed for a file variable opened the LOCKAUTO, SINGLE, and NOWAIT parameters.
     

    8. When a file variable is opened to use Linux OS PL/B read locks, the read locks are only used for these PL/B read statements:

     

    FILE

    READ

    AFILE

    READ, READKG, READKGP

     IFILE

    READ, READKS, READKP

 

 

See Also: Example Code, CLOSE, Disk I/O Instructions

 


PL/B Language Reference OPEN OPEN (FILE)