|
|
|
The &FILE OPEN verb connects to a file.
This verb has the following format:
&FILE OPEN ID=fileid
[ FORMAT={ MAPPED | UNMAPPED | UMMAPPED-DBCS | DELIMITED } ]
[ MAP={ $NCL | mapname } ]
[ KEYPAD={ BLANK | NULL } ]
[ KEYEXTR={ YES | NO } ]
[ DATA=exitdata ]
Operands:
(Mandatory) Identifies the file being opened. fileid must have previously been made accessible to NCL by the UDBCTL statement.
Specifies the file format processing requirement. The default is MAPPED which generally requires the use of Mapping Services operands on PUT and GET statements. A file record is processed as a complete entity by reading it into, or writing it from, an MDO. Mapping Services is used to reference, by symbolic name, individual fields within the record. For the special case where the map name is $NCL, the record is read into or written from standard tokens. Mapping Services is used to format or access the MDO containing the tokens. This provides data transparency by allowing tokens containing any data to be placed in file records for subsequent NCL access.
By processing a file in UNMAPPED format, any file records is processed using NCL tokens (but not Mapping Services). When reading a record the contents are segmented and placed into the tokens specified. When writing a record, all tokens are concatenated to form the actual record. No examination or translation of the token data takes place in either case.
Specifying FORMAT=UNMAPPED-DBCS is the same as FORMAT=UNMAPPED. However, if SYSPARMS DBCS=FUJITSU is in effect, DBCS translation between IBM DBCS and FUJITSU DBCS occurs.
FORMAT=DELIMITED provides processing that is used when reading into or writing from NCL tokens only. When reading a record, the contents are scanned for the delimiter character (X'FF') and each delimited section of the record placed into a separate token. However, no examination of the data takes place on writing so the use of this format with transparent data can cause unpredictable results.
Valid only if FORMAT=MAPPED is specified or defaulted, and specifies the name of the Mapping Services map used to interpret the file contents.
The map name specified must be registered within the Mapping Services Data Dictionary, or the data read from the file is effectively unmapped. The default name $NCL is a special case that allows NCL tokens to be used on PUT and GET statements instead of the MDO operand. The tokens are placed within a record structure that provides data transparency but is not compatible with the DELIMITED format files.
Nominates the padding character for short keys as either blanks (X'40') or nulls (X'00'). For most character-oriented or name-oriented keys, the default BLANK is satisfactory. However, if the file keys contain characters below X'40', then padding using NULL is recommended.
Specifies whether to extract the file key from the record as part of the data. When the default KEYEXTR=YES is specified or defaulted, the key is removed from ('squashed out of') the record by a GET operation, or inserted by a PUT operation. Hence processing proceeds as though the record and the key are separate entities.
When KEYEXTR=NO is specified, the key remains as part of the data on a GET operation but is still separately accessible through the &FILEKEY system variable. On a PUT operation, the key portion of the data record is assumed to be present but is ignored, and the current contents of the &FILEKEY variable are used to overlay the key within the data.
When processing using the &FILE verb, the &CONTROL KEYXTR setting is ignored. Key extraction is determined on the &FILE OPEN by the KEYEXTR operand.
Identifies any additional data to pass to a user exit on the &FILE OPEN. If used, this must be the last operand, and all data following the DATA= keyword is passed to the NCL &FILE validation exit (NCLEX01) without inspection.
Return Codes:
On completion of the operation, the &FILERC system variable is set as follows (certain return codes only apply if set by the validation exit NCLEX01, where this is in effect):
Restrict access to read only
Read with update ability, without delete
Read and update with delete ability
No access allowed
Specified fileid is not available (see &SYSMSG for details)
Return codes 0, 4, and 12 apply only if the validation exit NCLEX01 is in effect. Return codes 8 and 16 is set regardless of the exit being in effect.
Note: If no exit is in effect and the specified file ID is available for processing, no restriction to access applies and a value of 8 is set in &FILERC.
Failure of the procedure to limit processing within the bounds set by the processing exit, as indicated by the return code in &FILERC, results in termination of the procedure at the point at which an unauthorized function is attempted.
The use of a logical file identity as assigned by the &FILE OPEN statement makes it possible to use a single command (the UDBCTL command) to control the migration of all NCL procedures from one physical data set to another. The UDBCTL command associates a physical file with a logical name. These logical names are then valid for &FILE statements and provide a connection between the physical data set and the processing NCL procedure. This approach allows an installation to move all processing of NCL procedures onto another data set to free the previous data set for off-line processing. The approach also isolates procedures from any knowledge of real data set names and therefore makes JCL changes transparent to NCL procedures.
Each new file ID specified on an &FILE OPEN statement allocates sufficient storage to process subsequent requests associated with that file. The &FILE CLOSE statement is used to release file processing connections and any related storage. Termination of the NCL procedure also frees any associated storage.
The return code is tested to determine the cause of the error.
Important! Exercise great care while processing system data sets such as VFS. This type of processing must be performed using the UNMAPPED mode and requires an excellent understanding of the formats of the records in these data sets. Invalid processing of these data sets can cause unpredictable results and result in abnormal termination of the system.
Notes:
| Copyright © 2009 CA. All rights reserved. |
|