Declares an externally described disk file for processing in a program.
DCLFILECONT Db (Database Object)
File (*FILEDESC | Character Expression) DbDesc (Database Object | Character Expression) FileDesc (*NAME | Character Expression) XmlDesc (Character Expression) RnmFmt (*NONE | Old Format Name, New Format, ...) ShareType (*FILE | *EXCLUSIVE | *EXCLUSIVEREAD | *SHAREUPDATE | *SHARENOUPDATE | *SHAREREAD | Character Expression) ChkFmtId (*SAME | *IGNORE | *MAP | *YES | *NO | Indicator Expression) Prefix (prefix name, [Length]) Mbr (*FIRST | *FILE | Character Expression) NetBlockFactor (*CALC | *NONE | Number of Records to Block) CacheWrites (*NO | *YES | Indicator Expression) Commit (*NO | *YES | Boolean/Indicator Expression) QrySelect (*NONE | Character Expression) QryKeyFlds (*NONE | Character Expression) QryFileName (*Name | Character Expression) WaitRec (*FILE | *IMMEDIATE | *NOMAX | Time to wait) Random (*NO | *YES)
Required. Db specifies the Database Object declaration whose DBName specifies
where the compiler will acquire the file description. Db specifies the
Database Connection to use when opening the file at run-time. Database
Objects are defined with the DCLDB command.
Optional. File specifies the Library and File to use when opening the file at run-time.
If the File parameter is not given, the same file that was used to retrieve the description will be opened at run-time.
If a file name is given on the File parameter, that file will be accessed
and must have the same description as the file accessed in the Name parameter,
otherwise unpredictable results may occur. The File parameter accepts a
variable as a parameter, so that the file accessed can be overridden at
run-time.
Optional. Database description. Specifies the database to use during compile-time to access the File Description.
Database Object declaration whose DBName specifies where the compiler will acquire the file description. Database Objects are defined with the DCLDB command.
Character expression - the Database Name to get the description from. Used
in conjunction with FileDesc.
Optional. File description. Takes the description using the Name parameter to access a local Acceler8DB file on your PC. Use this parameter if the name of an Acceler8DB file uses characters not valid within RPG.
If you want to retrieve the description from a specific library or directory, use the FileDesc parameter to point to the particular file you want. This parameter must be a character literal, so the file description can be accessed at compile time.
*NAME (default) - takes the description using the Name parameter to access a local Acceler8DB file on your PC.
Character expression - the description of the Acceler8DB file.
Optional. Takes the description using the Name parameter to access a local XML
file on your PC. This parameter must be a character literal, so the file
description can be accessed at compile time.
Optional. Rename Format. Renames the old format to a new format, to avoid clashes with duplicate format names. *NONE is the default.
For single format files, you can specify RnmFmt (New Format Name) - which will automatically rename the only format in the file to the New Format Name. If you specify the syntax "Old format Name, New Format Name for single format files, the Visual RPG compiler will ignore the Old Format Name.
Optional. ShareType defines values on how a file will be shared. The default is *FILE.
*File (default) - maintains the same share type specified when the file was created.
*Exclusive - open for update, exclusive lock.
*ExclusiveRead - open for update, other jobs may read.
*ShareUpdate - open for update, other jobs may read or update.
*ShareNoUpdate - Open for read, other jobs may read.
*ShareRead - Open for read, other jobs may read or update.
Optional. ChkFmtId checks if the format ID of the file at run-time compares to the format ID of the file at compile-time. Visual RPG stores the format of file(s) when a program is first compiled. At run-time, Visual RPG compares the format ID that was stored during the compilation with the current format ID. The comparing of format ID's can be especially useful when checking if new fields have been added to a file used by a program that has been compiled months ago.
*SAME (default) - indicates that the run-time and compile-time format ID's will be compared to verify that they are the same. (This is exactly the same as *YES in previous releases).
*IGNORE - indicates that the run-time and compile-time format ID's will not be compared to verify that they are the same. Visual RPG will use the compile-time format ID. (This is exactly the same as*NO in previous releases).
Note: Please be extremely careful in using *IGNORE, as it has the risk of the corruption of data files and misbehavior of your application!!
*MAP - indicates that the run-time and compile-time format ID's will be compared, and Visual RPG will accommodate non-key fields added and changed regardless of where they are defined in the new record format. When the modified file is opened, Visual RPG will rebuild, or map its compiled record format at run-time to equal that of the new record format.
*YES - See *SAME above.
*NO - See *IGNORE above.
Optional. Prefix allows the specification of a string which is to be prefixed to the field names of an externally described record format. The characters specified as (prefix name) are prefixed of all fields defined in all record formats of the file.
You can also optionally specify a numeric value (length) to indicate the number of leading characters in the existing name to be replaced. If a length is not specified or is zero, the string is prepended to the name.
The total Length of a name after applying the prefix must not exceed the maximum length of an RPG field name.
If a Length is specified, it must be a numeric constant containing a value between 0 and 13 with no decimal places. Specifying a value of zero is the same as not specifying a length at all.
The Length parameter must not be greater than or equal to number of characters
in the name to be prefixed. That is, the resulting name cannot be the same as
the prefix string after the prefix is applied.
Optional. Mbr specifies the file member to use when opening the file at runtime. The Mbr parameter allows you to specify the name of the member you want to access or *FIRST. *FIRST is the default.
*FIRST (default) - will access the member with the oldest creation date.
*FILE - accesses the member name with the same name as the file name.
Optional. NetBlockFactor determines if and optionally how many database records will be blocked across the Network for better performance when reading or writing groups of records. Network blocking significantly reduces the network burden of transferring records between server and client machines, and this is demonstrated by the substantial increase of data throughput.
Unless NetBlockFactor is *NONE, network blocking is employed for input and output files as described below.
INPUT - The file is declared with Type(*INPUT) and AddRec(*NO). When an input file is "blocked", the buffered data resides on the client PC. This allows successive READ and READE statements to execute quickly. Be aware that should records be updated in other definitions of the file, those changed are not correspondingly updated in the buffer.
OUTPUT - The disk file is declared with Type(*OUTPUT) and Cachewrites(*YES). When an output file is "blocked", the buffered data resides on the client PC until the block has been filled or the file is closed. Then the block is sent to the server in a single transaction. Be aware that I/O errors at the server are returned only during processing of the block. In other words, if the 33rd record in a block of 100 records had a duplicate key, your application would not be aware of it until after writing the 100th record. Therefore, the use of network blocking for output files should be employed only when your application can be restarted.
I/O operations that will reset the buffer are SETLL, SETGT, SETRANGE, CHAIN (READRAND) and READRANGE. *CALC - The system will calculate the number of records to block. The blocking factor is 6000 divided by the file's record length. If the record length is greater than 3000 (1/2 the block size),
*CALC (default) will compute a record blocking Factor of 1 (one).
*NONE - No blocking will occur on the file. This is the default when the Type is other than *INPUT.
Record Count - The maximum number of records to include in the block. Note, the number of records in the block for SETRANGE with READ operations, and for READRANGE operations will be less than the record count if the set of records in the range is smaller than the maximum block size. Because of this dynamic blocking, the use of SETRANGE and READRANGE can realize even better performance than SETLL and READE, for example.
Note Record blocking requires additional memory to work. Blocking reserves memory for the complete block of each blocked file. For example, a record length of 2560 and a blocking factor of 100 will require an additional 256K of memory.
Optional. CacheWrites specifies whether data is written to disk immediately after an operation, or whether data is saved in a buffer, then written to disk when the Operating System has time. *NO is the default.
*NO (default) indicates that data will be written to disk at the time the operation is performed. Note that this option is slower than saving the data to a buffer.
*YES indicates that data operations will be saved to a buffer, and written to disk when the Operating System has time. Note that this option is faster. However, if the system fails with data in the buffer that has not been written to disk, the information will be lost.
When a disk file is declared with Type(*OUTPUT), Cachewrites(*YES) and
NetblockFactor (*CALC or value), output records are buffered at the client
before being sent as a block to the server database rather than being
transmitted one record at a time.
Optional. Commit allows you to control if commitment control will be enabled for this file. You can also change at runtime by specifying a Boolean/Indicator expression. The default is *NO.
The parameter must be set prior to opening the file. If the file is opened explicitly using the OPEN operation in the calculation specifications, the parameter can be set prior to the OPEN operation.
Use the COMMIT and ROLLBACK operation codes to group changes to this file and other files currently under commitment control, so that all changes happen together, or do not happen at all.
*NO (default) - indicates that commitment control is not enabled.
*YES - indicates that commitment control has been enabled.
Boolean/Indicator Expression - allows commitment control to be specified or
changed at runtime.
Optional. QrySelect specifies the selection expression used to determine which records are to be made available for processing. The select expression syntax is the same as for a Select/Omit expression in Acceler8DB.
QryKeyFlds can be used in conjunction with QrySelect parameters to specify ordering of the selected records. Use QryFileName to specify the name of the temporary query file created.
When using QrySelect, please Note
*NONE (default) - there is no selection expression available for processing.
The parameter can be a character literal or a character variable.
If there are any errors in the character expression, they will not be caught until the file is opened at run-time.
Selection expressions are evaluated during file open time. Therefore, a runtime
error will be generated during the opening of the file when a selection
expression error is encountered.
Optional. The QryKeyFlds parameter is used to specify the name of one or more key fields used to arrange the query records. Each key field is composed of a field name followed by optional attributes that determine the sorting order (ascending descending, or absolute value for numeric fields).
*FILE is the default, which specifies that the original keys in the file should be used.
*NONE specifies that the file has no keys.
Character Expression contains a string containing a keyfieldname and it's attributes, as described in the Syntax section below.
When specifying QRYKeyFlds with key fields that do not match the original file's key definition, you must also specify Random(*NO). In addition, in order to process the file in the sequence specified by the QRYKeyFlds parameter, you must specify ORG (*Indexed).
Valid input operations for RANDOM(*NO) files are limited to: READ, READP and SETLL when used with the new special values *START and *END.
Syntax: The syntax for the QryKeyFlds parameter is: (KeyFieldName Attributes …)
KeyFieldName Must be a valid field name in the file.
Attributes Consist of the following: *ASCEND, *DESCEND, or *ABSVAL. You can have as many attributes as you want after a field name as long as they conform to the rules below.
... Indicates that you can repeat the sequence for as many key fields as you want.
When using QryKeyFlds, please Note
Each key field name and attribute must be separated by at least one blank.
*ASCEND and *DESCEND cannot be applied to the same field.
*ABSVAL only applies to numeric fields.
The parameter can be a character literal or a character variable.
If there are any errors in the key fields expression, they will not be caught until the file is opened at run-time.
Use QrySelect in conjunction with QryKeyFlds to specify the selection
criteria indicating which records to select from a file. Use QryFileName to
specify the name of the temporary query file created. Selection expressions are
evaluated during file open time. Therefore, a runtime error will be generated
during the opening of the file when a selection expression error is
encountered. Example: QryKeyFlds ('CustNo *ASCEND ORDERDATE *DESCEND LINENO
TOTAL *ABSVAL *DESCEND') For more information on QryKeyFlds examples and using
open query files in Visual RPG, refer to the following link: Using Open Query
File in Visual RPG.
Optional. QryFileName specifies the name of the query file created for the QrySelect and QryKeyFlds parameters. If *Name is specified, which is the default, the file name given on the F-spec or DCLFILECONT command is used.
If the database access with this file is an AS/400 database, then the QryFileName is used both on the OVRDBF and the OPNQRYF commands used when opening the file.
For Acceler8DB databases, a temporary logical file is created in QTemp with the QryFileName as its name. You can use the special name '*UNIQUE' (don't forget the quotes) to guarantee that there will be no conflicts with other files residing in QTemp. You will receive errors if there are duplicate file names in QTEMP.
It is recommended the use of QryFileName('*UNIQUE') when working with Web Applications. Web Applications run under one user, the user that is specified in Acceler8DB Work with Database Names dialogue. Web Applications usually store Runtime Errors and MsgBoxes in $$Visual RPGErr.TXT.
*Name (default) - the file name given on the DCLFILECONT's Name parameter is used.
For more information on QryKeyFlds and using open query files in Visual RPG,
refer to the following link: Using Open Query File.
Optional. WaitRec specifies the waiting period for a record. *File is the default.
*File (default) - indicates that the properties of the file are used to determine how long it waits for the record.
*Immediate - it won't wait for a record.
*NoMax - it will wait indefinitely.
Optional. Random specifies whether random database processing using Keys and RRNs is allowed. *YES is the default, which determines the random database processing using keys and RRNs is allowed.
*YES - (default) specifies that random database processing using Keys and RRNs on op codes such as SETLL, CHAIN, etc., is allowed.
*NO - specifies that random database processing using Keys and RRNs is not allowed. This option is commonly used when the Keys look different at runtime from the compile time. The common scenario is when using QryKeyFlds and under this scenario *NO option must be used to avoid a runtime exception.
The only I/O operations allowed are:
Input - Read, ReadP and Setll with *Start or *End as the Keys. Any other operations throw compiler error - "Random Access Operation Not Allowed For File". The results of Read and ReadP depend on the ORG option and if *INDEXED read them sequentially based on the Key of the file and *ARRIVAL reads in arrival sequence in the file.
Output - Write and Update.
CLOSE
COMMIT
DCLDB
DCLDS
DCLDSFLD
DCLFLD
LOOKUP
DCLPRINTFILE
OPEN
ROLLBACK