CDS095 - Open File

CDS095

Open File

This routine should be used to open a data file. It provides for more complete error checking than normally found within an application, including error 0 (file locked by another task), error 12 (file not defined), and error 18 (insufficient privilege). It also can be used in an environment using both pro5 and bbj by forcing the bbj application to use the pro5 data server. It also supports opening encrypted files.

In addition, CDS095 is able to open a file that is not in the current directory, nor found using the prefix list since it tries to locate the file in the company subdirectory based on the first two characters of the file name. CDS095 also retrieves templates and tracks what files are currently open so that called routines that need to open a file that has already been opened, does not require a disk access, nor open the file more than once.

CDS095 is also used to define and open temporary work files that are described in the Dynamo Data Dictionary.

CALL "CDS095",ERR=XXXX, CHAN, FILNAM$, PAR$, DIMTPL$, KGEN$

Only the CHAN and FILNAM$ are required to be passed to CDS095.

CDS095

ERR Branch to line XXXX if unable to open the file, lock the file, or retrieve the template if so requested by the PAR$ options.

CHAN Channel# to be used. If passed with a value of zero, then CDS095 will call CDS088 to obtain an available channel and return that channel number to the calling program. It is Excellware's convention to use a channel variable of the file name (less the company code). For example, a data file named DSCM01 would use a channel number variable of CM01. If not passed as zero, then the file will be opened to the channel number passed. If there is already a file open to the channel passed, this file will be closed.

FILNAM$

Name of file to be opened. Will be returned including company directory prefix if file was not found in current directory or using prefix. If the first two characters of the file name are XX, CDS095 will replace the XX with the current company code.

To open an encrypted data file, append two colons and the file encryption password to the file name, i.e., MyFile::Password.

PAR$

Options which may be passed with values, blanks or as a null string.

PAR$(1,1)

Error messages

N	display no error messages (default)
Y	display all error messages
D	display all error messages, except if the file is not defined then no error message is displayed

PAR$(2,1)

Locking option

Y	lock file
N	do not lock file (default)
U	do not lock file, and pass channel number back to calling program if file has already been opened on a prior call. Note that use of this option requires the calling program to leave the file open and never close it. The menu processor will close the file and clear the `SMS_FILES` global variable until opened again.
P	Private file option. Do not lock file, and disable subsequent calls to CDS095 with `PAR$(2,1)` set to `"U"` to use this channel#.

PAR$(3,1)

Template option

Y	template is required. Exit with error 99 if template is missing or invalid. Application software that uses the template should set this parameter to `"Y"` when calling CDS095 so that error 47's are not encountered later in the application when a template variable is first referenced.
N	template will be returned if available for data files, no error if not available (default)
P	template will be returned if available for data files and programs, no error if not available
X	bypass all template lookup logic. This can be used to improve performance by bypassing template file searching when the application does not use a template with this file.

PAR$(4,1)

Temporary work file option

W Define temporary work file, prior to opening. This option requires an entry in the data dictionary with a period at the end of the file name. However, you do not include the period in the FILNAM$ when calling CDS095. CDS095 will create a file in the tmp/ directory with a suffix of .x where x is a number to make the file name unique. See examples. Note that files defined in the tmp/ directory are erased by the menu processor when the application returns to the menu, and do not have to be erased by the application. CDS095 will return the specific file name created in FILNAM$ should the application need to close and reopen this file, or pass the file name to another routine such as CDS037 or CDS038.

PAR$(5,1)

Template search locations, passed to CDS041 to limit ways to search for template. This option is rarely required by an application program, since normally you want to retrieve the template using the default methods.

blank or not passed	treat as `Y` if `FILNAM$` is a program, `N` if not (default)
N	search global variable, tpl file
Y	search global variable, tpl file, Data Dictionary
D	search Data Dictionary only
T	search tpl file only
F	search tpl file and Data Dictionary, but not global variable

DIMTPL$ Dimensioned template returned by CDS095 to calling program as set by CDS041. For data files and programs with six character program names, the convention is to use the file name, less the company code, as the dimensioned template variable. For example, the data file XXCM01 would use CM01$. For 5 character programs, the company name is not a part of the program name, so the convention is to use the entire 5 character program name. For example, the program GL018 would use GL018$.

KGEN$ is used in the KGEN() function as the adjusted FIN() data. The KNUM alone, and not +256 option is sufficient since KGEN$ excludes all key segment modification flags such as descending segments, or business math. It is Excellware's convention to use the file name, less the company code followed by a K as the KGEN$ variable. For example, the data file XXCM01 would use CM01K$. The key derived from the data would be KGEN(DIMTPL$,KGEN$,KNUM).

Note that files opened by the menu processor use the Excellware convention and assign the channel number, dimensioned template and key generation variables. For example if file XXCM01 is opened by the menu processor, then the application will have the variables CM01, CM01$, and CM01K$ already assigned proper values.

Note that CDS095 may be used to open tty devices but not printers. See CDS084 for opening printers.

Should CDS095 fail to open a file for any reason, the error message is returned in the global "SMS_CDS095.ERRMSG". This is especially useful with background tasks including Dynaweb where the error message cannot be readily displayed.

BBj

Pro5 and bbj use different file locking techniques, so they both cannot open the same data file at the same time. In a mixed environment where both pro5 and bbj processes need to access data files simultaneously, you can set a global variable named SMS_PRE to the dataserver prefix that bbj should use such as /<localhost,port=1100>. When this global is set, CDS095 will only open data files using a dataserver, either a dataserver contained within the prefix list, or the dataserver prefix specified by the global variable. This global can also be specified using the background script or by the cgi script to enable Dynaweb applications to use bbj.

Examples

Opening a non-templated data file using default options. The application will use the numeric variable SK00 to access the file. If the numeric variable SK00 is zero, then CDS095 will set SK00 to an unused channel number. If SK00 has a non-zero value when passed to CDS095, then CDS095 will use the value passed, and close the file currently opened to this channel.

CALL "CDS095",ERR=XXXX,SK00,"XXSK00"

Opening a templated data file using default options.

CALL "CDS095",ERR=XXXX,CM01,"XXCM01","",CM01$

Typical data file READ statement:

READRECORD (CM01,KNUM=0,KEY=CUSTNO$,DOM=XXXX)CM01$

Typical data file WRITE statement:

WRITERECORD (CM01)CM01$

Opening a templated data file using default options with KGEN field.

CALL "CDS095",ERR=XXXX,,"XXVM60","",VM60$,VM60K$

Typical data file REMOVE statement. The advantage of using the KGEN function on the REMOVE, is that the program becomes independent of the file's key structure. If the key structure is changed, then the program does not need to be changed.

REMOVE (VM60,KEY=KGEN(VM60$,VM60K$,0))

Opening a data file within a called routine which may be called more than once. The "U" parameter will return CM01 with the channel number if the file is already opened, eliminating any disc access on subsequent calls. If the XXCM01 file is not already opened, then CDS095 will open it and assign the channel variable CM01.

CALL "CDS095",ERR=XXXX,CM01,"XXCM01","YUY",CM01$

Opening and locking a templated data file.

CALL "CDS095",ERR=XXXX,CM01,"XXCM01","YYY",CM01$

Defining a temporary work file based on file definition stored in the data dictionary. The data dictionary file name must include a trailing period (VM040.), but it is not included in the FILENAME$ passed to CDS095. In this example, the data dictionary company DY was used since the VM040 program was located in the DY/ directory.

READY
>FILENAME$="VM040"
>CALL "CDS095",VM040,FILENAME$,"YYYW",VM040$,VM040K$
>?FILENAME$
./tmp/VM040.9754
>?VM040
10
>?FATTR(VM040$)
SEQNO:U(2),VENDNO:C(6),MATCH:C(34),VM03SEQ:U(1)

Defining a temporary work file where the company code is included in FILENAME$. The EX data dictionary is used in this example with a file name of "T220.".

READY
>FILENAME$="EXT220"
>CALL "CDS095",T220,FILENAME$,"YYYW",T220$
>?T220
10
>?FILENAME$
./tmp/EXT220.9754
>?FATTR(T220$)
EMPNO:C(3),JOBNO:C(8),DATE:U(3),CUSTNO:C(6),ALPHASORT:C(8),HOURS:B:omask=##.0:,MILEAGE:U(2):omask=###:,EXPENSE:B:omask=####.00:

Example opening an encrypted file

CALL "CDS095",PR01,"XXPR01::MyPassword","YNY",PR01$