PREPARE (FILE)

ANSI

A file must be created or opened prior to any attempt to process data against it. The PREPARE (which may be abbreviated as PREP) instruction opens an existing file or creates a new file if the file does not exist.

(1)	[label]	PREPARE	{file},{txtname}[,{mode},VIEW={viewstring}:
			CANCELKEY={cancelkey},CHECKTIME={checktime}]
(2)	[label]	PREPARE	{file},{txtname\|tcpip id:port}[,{mode}:
			CANCELKEY={cancelkey},CHECKTIME={checktime}:
			VIEW={viewstring}]

Where:

label

Optional. A Program Execution Label.

file

Required. A previously defined FILE variable that is created or opened.

name

Required. A previously defined Character String Variable or Literal containing the physical text file name to create or 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.

mode

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

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.6A)

checktime

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

Flags Affected: NONE

Note the following:

{txtname} is the name of the physical text file opened. If a character string variable is specified, only the Logical String is used. If a literal is specified, the entire literal string, within the operating system's limitations, is used.
If the file already exists, a PREPARE acts the same as an OPEN instruction.
Which, if any, extension is assumed is as follows:

Compiler	Action
SUNDB86x	if no extension is specified and the file name is terminated with a period (.), no extension is assumed. Otherwise, the extension TXT is assumed.
PLBCMP	The current screen definition file in use 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 Text file extension specified in the screen definition file is utilized.

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"

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.

If still unable to locate the file, it is created in the directory specified by the PLB_PREP environment variable or the current directory if PLB_PREP is not present in the environment table.

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

If an extension is found, the '/' extension delimiter is changed to a Sunbelt extension delimiter character defined in the screen definition file. The default extension delimiter would replace the '/' delimiter with a period.
If the file name contains more than one '/' character and does not contain a colon (:), the file name is not evaluated for a Datapoint extension. If a file name contains a single '/' character, the file name is evaluated for a Datapoint extension.
The ':drv' specification in a Datapoint filename is changed to a substituted string defined by a UET keyword that must be defined by appending the Datapoint drive identification string to 'PLBVOL_'. In the above case, the UET string must be defined as 'PLBVOL_DRV={path}' in the environment table or in the 'PLBWIN.INI' file. If the UET keyword is not found, the runtime attempts to open the file with no changes. However, if the UET keyword is found, the runtime changes the filename to '{path}\filename.ext'.

Example: UET has environment entry defined as PLBVOL_D1=c:\data

PREP FILE,"name/txt:D1"

The actual file is prepared as c:\data\name.txt.

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

PREP FILE,"$ARDATA\company1.txt"

The actual file is created as '\\server2\acct\ar\company1.txt'.
For PLBCMP-GUI, if a null file name is used, the standard create dialog is displayed to allow the user to select the appropriate file.
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:

PREP	FILE,"B:FILENAME"	(MS-DOS)
PREP	FILE,"/usr/files/fname"	(Linux)

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

The first format allowed is nnn.nnn.nnn.nnn where each nnn value can be a value between zero and 255. This identifies the IP address of the server executing the Data Manager.
The second format provides the Domain Name System (DNS) string that can be translated by a DNS Server to identify the host IP server address executing the Data Manager.

{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.
File names that are in excess of operating system allowances are truncated to meet those standards.
Files resident on a Datapoint RMSRAS server may be created.
Attempting to PREPARE a file 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).
The optional {mode} parameter, if used, must be the last parameter on the instruction.
The {mode} may be a keyword or a decimal number or Numeric Variable as follows:

Valid keywords are EXCLUSIVE, READ, SHARE, and SHARENF.
If not specified, a MODE of SHARE is assumed.
The string "MODE=" followed by a decimal number or Numeric Variable (four byte INTEGER) containing bit maps as follows:

Keyword	Value	Meaning
CMP_EOR_MASK	0xF	Mask for all EOR bit definitions
CMP_EOR_CR	0x1	MODE input request EOR type CR only.
CMP_EOR_CRLF	0x2	MODE input request EOR type CRLF.
CMP_EOR_LF	0x4	MODE input request EOR type LF only.
CMP_EOR_LFCR	0x8	MODE input request EOR type LFCR.
CMP_OPEN_MASK	0x70	File mode mask in OPEN/PREP.
CMP_SHARE	0x0	Share mode requested in OPEN/PREP when no bit is set within the bit definition mask range defined by CMP_OPEN_MASK
CMP_EXCLUSIVE	0x10	Exclusive mode requested in OPEN/PREP.
CMP_SHARENF	0x20	Share NoFlush requested in OPEN/PREP.
CMP_READ	0x40	Read mode requested in OPEN/PREP.
CMP_NOTEMPCLOSE	0x80	Keep file open across EXECUTE statements.
CMP_NOPREPTRUNC	0x400	Prep AFILE/IFILE without truncating the txt file.
CMP_NO_TRAN	0x1000	Do not put this file under a transaction. (9.0)
CMP_RESERVED_1	0x20000	DO NOT USE. This bit is ignored by the runtime. (9.6)
CMP_RESERVED_2	0x400000	DO NOT USE. This bit is ignored by the runtime. (9.6)
CMP_RESERVED_3	0x80000	DO NOT USE. This bit is ignored by the runtime. (9.6)
CMP_DONOTUSEIP	0x100000	Ignore the PLB_OPENUSEIP and PLB_PREPUSEIP keywords. Also, this bit definition indicates that a '\|' redirection character in a file name is to be ignored. This bit gives the PLB application the flexibility to allow individual file variables to always be processed local to a client with minimal changes to the application while other file variables are generically being redirected to a Data Manager. (9.6)
CMP_NOSQLIO	0x200000	If this bit value is specified in the MODE bit mask values, the PREPUSESQL and OPENUSESQL keywords are not used for the FILE, IFILE, or AFILE being opened or prepared. This bit mask value also applies to the SETMODE PREPUSESQL and OPENUSESQL keywords. (9.6B)
CMP_NOSHRINK	0x4000000	The TXT data file does not get smaller. The PL/B runtime can optimize direct READ operations using the TXT data file. (9.6C)
CMP_LOCALCDF	0x1000000	This {mode} bit setting enables the Windows locale mode which causes the *CDFON delimiter character (i.e., normally comma) to be replaced by the Windows List Separator locale character setting (i.e., single character used!). (9.8A - Windows Only)
CMP_RESERVED	0x80000000	DO NOT USE. This bit is ignored by the runtime.

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.
If the same File Definition Label ({file}) is opened or prepared within the same program, the currently open file is CLOSEd before an attempt is made to initialize the new file.
The default sector size for the file is 256 bytes unless modified through the BUFFER/FIX/FIXED parameter in its declaration.
Operating system standard devices (COM1:|LPT1: under MS-DOS, /dev/lp1|/dev/tty01 under Linux) may be opened as files and processed using the sequential -1 or -2 access methods. However, the success of this type of technique depends upon the programmer's knowledge of the environment and any interface requirements. Sunbelt may provide examples of this technique but does not guarantee its practicality for use or provide support, except on a time and material basis.
When a CLOSE is the first I/O instruction following the PREPARE, the file is deleted from the disk. This may be accomplished with the ERASE verb.
Each FILE requires a single operating system file handle. The maximum number of files that may be opened concurrently is limited to those restrictions imposed by the environment in use.
If a FILEPI is active and {txtname} is null causing activation of the file dialog, the FILEPI is terminated.
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"
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.
Before a view can be used in an OPEN instruction, the view schema data must already exist in a Schema Database that is being used. The SCHEMA instruction using the IMPORT keyword loads the view data into a schema database.
The {cancelchar} value specifies the AAM cancel character or key that aborst an AFILE READ operation (9.6A). If the {cancelchar} is a NULL variable or literal, the AAM cancel support is disabled for this AFILE variable. If this keyword is not specified, the AAM 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:

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

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 AAM cancel character feature is determined by the current program/runtime default settings.