PREPARE (IFILE)

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.

ifile

Required. A previously defined IFILE 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.

isiname

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

maxkeylen

Required. A previously defined Numeric Variable, Literal, CONST, or Expression defining the maximum key size.

keyspecs

Required. A previously defined Numeric Variable, Numeric Literal, CONST, Expression, Character String Variable or Character Literal defining the key.

maxreclen

Required. A previously defined Numeric Variable, Literal, CONST, or Expression defining the maximum record.

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)

cachesize

Optional. A previously defined Numeric Variable or Literal defining the ISI cache setting. (9.6C)

Flags Affected: NONE

Note the following:

1. {txtname} is the name of the physical text file (txt) prepared and {isiname} is the name of the ISAM key file (isi). 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 ISI for {isiname}.
PLBCMP	The current screen definition file in use 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 ISAM 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 current 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	IFILE,"name1/txt:data":
	"name2/isi:index","10","256"


The actual data file is prepared as c:\data\name1.txt. The actual ISAM file is prepared as c:\index\name2.isi. 

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	IFILE,"$ARDATA\company1.txt":
	"$ARDATA\company2.isi","10","256"


The text file is prepared as '\\server2\acct\ar\company1.txt' and the ISAM file is created as '\\server\acct\ar\company2.isi': 

 

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:

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 {isiname} exists, its ISAM tree is cleared. {txtname}, if it exists, is also cleared and all data records overwritten.

13. The {keyspecs} parameter can be specified as a numeric variable or literal or as a string variable or literal.

• When a numeric variable or literal value is detected, the value identifies the maximum key length for the ISAM file being created. An IFILE created in this manner causes an IO error if it is used in a FILELIST.

• When the {keyspecs} is specified as a string variable or literal, the string must contain key specifications as used by the SUNINDEX utility. The key specifications identify the location in a record from which the ISAM key can be retrieved when using the IFILE in a FILELIST.

14. The sum of the key specifications cannot exceed 150 positions.

15. {maxreclen} must be a valid numeric variable, literal or constant in the range of one (1) to 32,767 inclusive that defines the maximum record size written to the IFILE. The declared sector size (BUFFER/FIX/FIXED) must be equal to or greater than, {maxkeylen} or else an I/O error occurs (I47).

16. The maximum key length, record length and the text file name are all stored in the {isi} file for future retrieval by OPEN instructions.

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

18. 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_ISI_BLOCK	0x100	Allocate and extend the ISI file by eight ISAM sectors (4096) bytes. This improves performance of applications that write a large number of ISAM record in a batch mode. (8.7)
CMP_NOPREPTRUNC	0x400	Prep IFILE without truncating the text file.
CMP_BY_OSTYPE	0x800	Set ISI header flag that only allows opening of the index file by a compatible Windows or Linux runtime.
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_ISICOMPACT	0x8000	Enable ISI compacting for the specific IFILE variable.
CMP_NOISICOMPACT	0x10000	Disable ISI compacting for the specific IFILE variable.
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.

 

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

20. If both the CMP_ISICOMPACT and CMP_NOISICOMPACT bit mask bits are set to a zero bit value or to a one bit value, the runtime uses the current default behavior that is being used by the runtime for the compacting action.

21. If the same File Definition Label {ifile} is opened or prepared 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 IFILE requires two operating system file handles (one for the text file and one for the ISAM 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 activation of the file dialog, the FILEPI is terminated.

24. When a PREP statement for an IFILE variable with the NOPATH parameter specified is performed, any path information is stripped from the text filename before it is placed into an ISI 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 ISI header.

25. It is not good programming practice to use more than one user program to PREP the same ISI files in a multi-user environment. The default action for the PREP instruction for an IFILE 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 ISI files.

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

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

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

29. The {cancelchar} value specifies the AAM cancel character or key that aborts 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

 

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

31. The {cachesize} keyword overrides the current runtime ISI caching default setting. By default the PLB runtimes enable ISI caching with the cached sector count set to fifty percent (50%) of the maximum count allowed. The maximum allowed count is two hundred (200) sectors. The {cachesize} value can be specified from zero to two hundred. A value of zero disables the ISI caching. (9.6C)

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