PREPARE (AFILE)

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 (clearing any associated key files) or creates a new file and key file if the file does not exist.

Where:

label

Optional. A Program Execution Label.

afile

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

txtname

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

aamname

Required. A previously defined Character String Variable or Literal containing the AAM key 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.

keyspecs

Required. A previously defined Character String Variable or Literal containing no more than 95 AAM key specifications and any options selected.

maxreclen

Required. A previously defined Numeric Variable, Literal, or Expression up to 32k bytes and is the maximum record size written to the AFILE.

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

checktime

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

Flags Affected: NONE

Note the following:

1. {txtname} is the name of the physical text file (txt) prepared while {aamname} is the name of the AAM key file (aam). If a character string variable is specified for either, 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:

 

Compiler	Action
SUNDB86x	If no extension(s) are specified, and the filename(s) are terminated with a period (.), no extension is assumed. Otherwise, the default extension is TXT for {txtname} and AAM for {aamname}.
PLBCMP	The current screen definition file determines whether an extension is required or not. If not and the file name was terminated with the `Filename to extension delimiting character' in the screen definition file, no extension is assumed. Otherwise, the Text and/or AAM extensions specified in the screen definition file are utilized.

 

3. 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.

4. 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_DATA=c:\data and PLBVOL_INDEX=c:\index
   

PREP	AFILE,"name1/txt:data":
	"name2/aam:index","1-10","99"


The actual data file is prepared as c:\data\name1.txt. The actual AAM file is prepared as c:\index\name2.aam. 

5. 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	AFILE,"$ARDATA\company1.txt":
	"$ARDATA\company1.aam","1-10"


The data file prepared is '\\server2\acct\ar\company1.txt' and the AAM file is ''\\server\acct\ar\company2.aam'. 

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

7. 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	AFILE,"C:TEXT","D:AAM","1-10","99"	(MSDOS)
PREP	AFILE,"/data/text":
	"/amdx/aam","1-10","99"	(Linux)

8. Format (2) above includes 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.

9. {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.

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

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

12. If {aamname} exists, its AAM tree and the TXT file are both cleared.

13. {keyspecs} is a character string variable or literal containing up to 95 AAM key specifications and any options selected. If {keyspecs} is a character string, only the Logical String is used.

14. The AAM keys, up to 95, may overlap (1-10,5-15) or be wholly within another (1-10,3-9) and may be located anywhere within the record. In addition to the key specifications, the supported options are:

 

Option	Use
D={c}	Where {c} is the wildcard character for READ instructions.
U	Specifies non-case sensitive searches (upper/lower case treated the same).
Px={yy}	Specifies the primary record indicator. The indicator starts in column 'x' and must exactly match the characters in {yy}. {yy} may be from 1 to 8 characters.
X	Must immediately precede a key specification and specifies that the key is not placed in the AAM file butis for look up purposes only. More that one key specification, but not all, may be preceded by an 'X' specification. At least one non-excluded key specification must be used when reading a record.

15. The `U' option, when used, must be the first item in the key specification list. If the `D=' option is used, it should immediately follow the `U' option when both are used. Otherwise, it should be the first item in the key specification list.

16. {maxreclen} must be a valid numeric variable or literal, up to 32k bytes and is the maximum record size written to the AFILE. The declared sector size (BUFFER/FIX/FIXED) must be equal to or greater than, {maxreclen} or else an I/O error occurs (I47).

17. The key specifications (including the case sensitivity and wildcard options), record length and the text file name are stored in the {aamname} file for future retrieval by OPEN instructions.

18. The optional {mode} parameter, if used, must be the last parameter on the instruction.

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

    Valid keywords are EXCLUSIVE, READ, SHARE, and SHARENF (non-ANSI).

    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 without truncating the text file.
CMP_BY_OSTYPE	0x800	Set AAM header flag that only allows opening of the index file by a compatible Windows or Linux runtime. (9.0)
CMP_NO_TRAN	0x1000	Do not put this file under a transaction. (9.0)
CMP_PREP87	0x2000	Create file using version 8.7 format
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_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.

20. 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.

21. If the same File Definition Label ({afile}) is opened a second time within the same program, the currently open file is CLOSEd before an attempt is made to initialize the new file.

22. 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.

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

24. A PREP operation may use a MFD file descriptor to redirect the operation to the SUNDM data manager. The default action of a PREP instruction is to detect the presence of a MFD file descriptor and initiate a SUNDM PREP operation. The user can override this default action by the runtime keyword PLB_PREPBYMFD or by the SETMODE keyword *PREPBYMFD. When a PREPBYMFD keyword is set to OFF, the prepare operation does not attempt to detect a MFD file descriptor and performs the PREP operation according to normal guidelines.

25. When a PREP statement for an AFILE variable with the NOPATH parameter specified is performed, any path information is stripped from the text filename before it is placed into an AAM file header. The use of the NOPATH option helps to resolve situations where a full path and filename may be larger than 47 characters that is a size limit of the text filename placed into the AAM header.

26. It is not good programming practice to use more than one user program to PREP the same AAM files in a multi-user environment. The default action for the PREP instruction for an AFILE is to truncate the text data file and initialize the index files. Improper use of PREP can result in corrupted or lost records when executed by multiple users against the same AAM files.

27. 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 can initially establish 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.

28. 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.

29. When using SQLIO support, the {keyspecs} and {maxreclen} parameters in the PREPARE instruction are not used and do not alter the SQLIO schema definitions. However, the {keyspecs} are still validated by normal native index key spec processing in the runtime.

30. The {cancelchar} value specifies the AAM cancel character or key that aborts an AFILE READ operation (9.6). 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

 

31. The {checktime} value specifies the elapsed time in seconds used when checking for abort key (9.6). 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.

See Also: Example Code, OPEN (AFILE), CLOSE, Disk I/O Instructions