GETFILE

8.1

 

The GETFILE instruction retrieves information from a file or FILELIST variable. The instruction uses the following format:

 

 

[label]

GETFILE

{file},{keyword}={value}[,{keyword=value}...]

 

Where:

label

Optional. A Program Execution Label.

file

Required. A previously defined AFILE, DBFILE, FILE, IFILE, COMFILE, PFILE, FILELIST, or ADMIN variable.

keyword

Optional. If specified, one of the valid keywords defined below.

value

Required. A previously defined Character String Variable or Numeric Variable in which the value is returned.

Flags Affected: ZERO, EOS, OVER

Note the following:

  1. If the file specified is not open, the ZERO flag is cleared and the variables remain unchanged. If the file is open, the ZERO flag is set. If the file is a FILELIST, the zero flag is only set when all of the AFILE\IFILE files in the FILELIST are opened. If any file in the FILELIST is closed, the ZERO flag is cleared and the variable(s) for a keyword may be changed for any opened files in the FILELIST.

  2. If the value returned to a string variable is longer than the variable, the EOS flag is set.

  3. If the value returned to a numeric variable overflows the variable, the OVER flag is set.

  4. All requests that return a numeric variable will return a value of zero (0) for an invalid request.

  5. The following keywords may be used:

    6.  

    Keyword

    Returns the ...

    AAMDEXINFO={svar}

    command line that will create the .AAM file using the sunaamdx utility. Since the .AAM file does not contain the actual command line, the AAMDEXINFO keyword builds the command line in the same manner as if the 'sunaamdx aamfile -i' command were executed.

    AAMCANCELCHAR={svar}

    current setting being used for the AAM cancel character support as applied for the specified AFILE variable. If the AAM Cancel character is not being used, the {svar} variable is set to NULL. Otherwise, the {svar} is set to the character or key name as specified by the PLB_AAMCANCELCHAR INI keyword. (9.6)

    AAMCANCELFLAG={nvar}

    flag value of zero (0) or one (1) depending on whether the last AFILE READ operation was aborted using an AAM cancel character. The value of one indicates that an AFILE READ was terminated by an AAM Cancel character. This flag persists until the next AFILE READ operation.(9.6)

    AAMCHECKTIME={nvar}

    current setting being used for the AAM cancel character support as applied for the specified AFILE variable. The returned value is the same as described for the PLB_AAMCHECKTIME INI keyword.(9.6)

    AAMNAME={svar}

    qualified AAM file name.

    AHANDLE={nvar}

    AAM file handle.

    BUFSIZE={nvar}

    declared buffer size.

    CANCELCHAR={svar}

    current setting being used for the cancel character support as applied for the specified FILE, AFILE, or IFILE variable. If the cancel character is not being used, the {svar} variable is set to NULL. Otherwise, the {svar} is set to the character or key name as specified by the PLB_CANCELCHAR INI keyword. (9.6A)

    CANCELFLAG={nvar}

    flag value of zero (0) or one (1) depending on whether the last FILE, AFILE, or IFILE READ operation was aborted using an cancel character. The value of one indicates that an READ was terminated by an cancel character. This flag persists until the next READ operation.(9.6A)

    CDFDELMCHAR={svar]

    *CDFON user defined delimiter character which was determined when the file variable was opened or prepared. If the returned {svar} is NULL, there is no user defined delimiter substitution being used for the file variable and thus, the normal comma delimiter is used.

    CHECKTIME={nvar}

    current setting being used for the cancel character support as applied for the specified FILE, AFILE, or IFILE variable.(9.6A).

    DELETECOUNT={nvar}

    current deleted record count from an ISI header. (9.0)

    DMISCONNECTED={nvar}

    a value as described below that identifies whether a file variable is currently connected to a data manager. If the current working state for the connection is determined to be bad, the file variable can be re-opened without having any I81 errors.

    EORTYPE={nvar}

    end of record type as described below.

    FILEFORMAT={nvar}

    file format as described below. (9.0E)

    FILELISTNAMES={svar}

    the 'NAME={filename}' declaration keyword information for the AFILE/IFILE file variables that have been include in the FILELIST. (9.5A)

    FILTER={svar}

    filter string for a specified FILE, AFILE, or IFILE. If a filter string does not exist, a NULL DIM variable is returned. The maximum size expected for a filter string is 4096 bytes. (9.4B)

    FPOSITASIZE={nvar}

    the current minimum size required for the {pos} variable in the FPOSITA instruction. Please note that the FPOSITASIZE size can vary depending on the keys used for the last AFILE IO operation. (9.1)

    GETSUNDMIP={svar}

    current TCP/IP address for the SUNDM Data Manager. The returned TCP/IP string is the IP4 format that is 'nnn.nnn.nnn.nnn'. This TCP/IP address is the resolved address used for the socket connection to the SUNDM Data Manager. This keyword is valid for an AFILE, FILE, or IFILE file variable. If the AFILE, FILE, or IFILE file variable is opened but not through the SUNDM Data Manager, the {svar} variable is nulled. If the AFILE, FILE, or IFILE file variable is not opened, the {svar} variable remains unchanged.(9.3B)

    GETSUNDMPORT={svar}

    current port number used to access the SUNDM Data Manager. The returned port number string is a decimal number. This keyword is valid for an AFILE, FILE, or IFILE file variable. If the AFILE, FILE, or IFILE file variable is opened but not through the SUNDM Data Manager, the {svar} variable is nulled. If the AFILE, FILE, or IFILE file variable is not opened, the {svar} variable remains unchanged.(9.3B)

    HANDLE={nvar}

    text file handle.

    HDC={nvar}

    Windows current device context associated with a PFILE printer. If the HDC keyword is executed under a runtime other than PLBWIN, the value returned is always zero. When using the HDC keyword, a value of zero indicates that there is no device context available. The ZERO flag identifies when a valid value is retrieved. The HDC value provided with this statement can be used in WINAPI statements to perform actions for the PFILE device outside the scope normal PL/B PFILE operations.

    IHANDLE={nvar}

    ISI file handle.

    INDEXINFO={svar}

    the index command line string from the header of an ISI file. This option is only allowed for an IFILE. (9.0F)

    ISIFLAGS={nvar}

    index options flags from the header of an ISI file as defined below. This option is only allowed for an IFILE. (9.0F)

    ISINAME={svar}

    qualified ISI file name.

    ISIRECORDLEN={nvar}

    current record length from the header of an ISI file. The {nvar} value is this case does not include the end of record byte count. The {nvar} value in this case only reflects the maximum number of data bytes allowed in a record in the text file associated with the ISI file. This option is only allowed for an IFILE. (9.0F)

    ISITEXTEOF={nvar}

    current text end of file value from the header of an ISI file. If the ISI file is indexed for large file support, the returned value is a record count for the record count of the last record written into the text file. If ISI file is not indexed for large file support, the returned value is the byte offset for the eof size. This option is only allowed for an IFILE. (9.0F)

    ISMANAGED={nvar}

    status flag to indicate when a file has been opened under the Data Manager control. When the return value is zero, the file is not opened via the Data Manager. When the return value is one, the file is currently opened under control of the Data Manager.

    KEYLENGTH={nvar}

    keylength from the header of an ISI file. This option is only allowed for an IFILE. (9.0F)

    MODE={nvar}

    open mode as described below.

    NAMETYPE={nvar}

    file type as described below.

    OSLOCALEDELMCHAR={svar}

    Windows locale list separator character available when the file variable was opened or prepared. This keyword provides information only and does not have any impact on the behavior of the *CDFON control. If the returned {svar} is NULL, there was no OS locale list separator available when the file was opened or prepared. The Linux\Linux runtime and data managers do not have locale list separators and therefore a NULL is expected.

    PRTNAME={svar}

    name stored for a PFILE.

    QUERYCOLCOUNT=<nvar>

    number of columns included in the last query result set when using a SQLite database. When there is no last query result set, a zero value is returned. The file variable for the GETFILE instruction can be a DBFILE or DBSTATEMENT reference. (9.4)

    QUERYCOLNAMES=<svar>

    column names that are included in the last query result set when using a SQLite database. When there is no last query result set, a null {svar} variable is returned. The file variable for the GETFILE instruction can be a DBFILE or DBSTATEMENT reference. The column names are returned in the {svar} variable as comma delimited names. (9.4)

    QUERYCOLUMNS=<svar>

    the same as the QUERYCOLNAMES keyword except the delimiter character for the QUERYCOLUMNS keyword is a semicolon (;) character. The QUERYCOLUMNS keyword is implemented to avoid a delimiter conflict when an SQL select statement includes a function. (9.4C)

    QUERYCOLTYPES=<svar>

    the column types that are included in the last query result set when using a SQLite database (9.4C). When there is no last query result set, a null {svar} variable is returned. The file variable for the GETFILE instruction can be a DBFILE or DBSTATEMENT reference. The column types are returned in the {svar} variable as comma delimited types. The SQLite datatypes values are defined as follows:

    1 = SQLITE_INTEGER

    2 = SQLITE_FLOAT

    3 = SQLITE_TEXT

    4 = SQLITE_BLOB

    5 = SQLITE_NULL

     

    The QUERYCOLTYPES should be executed before the last row of data is retrieved using a DBFETCH instruction. If all of the rows of data are retrieved before the QUERYCOLTYPES is executed, the column types are all returned with the SQLITE_NULL column type.

    RECORDCOUNT=<nvar>

    current record count from an ISI header. (9.0)

    SCHEMAINFO={svar}

    schema information associated with the GETFILE {file} variable. The schema data is stored in XML format. (9.4)

    SQLIOCONN={svar}

    login information as specified\described by the following:

    1. Sun_Sqlio_Databases schema 'conn' column.

    2. PLB_SQLIO_CONN runtime keyword.

    3. The 'SETMODE *SQLTABLEDB' keyword under the Note (3). (9.8B)

    SQLIODATABASE={nvar}

    database name that exist on the SQL database engine where the file variable SQLIO data table exists. This database name may be specified in the 'Sun_Sqlio_Databases' administration schema table under the 'name' column. Otherwise, it may be specified by the <sql> attribute named 'database={databasename}' found in the 'SQLIO PLB Language Changes' section in the 'PL/B Language Reference' manual. (9.8B)

    SQLIOEXT={svar}

    extension data as specified\described by the following:

    1. Sun_Sqlio_Databases schema 'ext' column.

    2. PLB_SQLIO_EXT runtime keyword.

    3. The 'SETMODE *SQLTABLEDB' keyword under the Note (3). (9.8B)

    SQLIOHOST={svar}

    the database source as specified\described by the following:

    1. Sun_Sqlio_Databases schema 'host' column.

    2. PLB_SQLIO_HOST keyword.

    3. The 'SETMODE *SQLTABLEDB' keyword under the Note (3). (9.8B)

    SQLIOPASS={svar}

    password as specified\described by the following:

    1. Sun_Sqlio_Databases schema 'pass' column.

    2. PLB_SQLIO_PASS runtime keyword.

    3. The 'SETMODE *SQLTABLEDB' keyword under the Note (3). (9.8B)

    SQLIORECORDS={nvar}

    <SQL> 'RECORDS' attribute. (9.6B)

    SQLIOTABLE={svar}

    name of the SQL table that is being used and contains the data for the file variable used for the SQLIO operations. This table name may be specified in the 'Sun_Sqlio_File' administration schema table under the 'table_name' column. Otherwise, it may be specified by the <sql> attribute named 'table_name={tablename}' keyword found in the 'SQLIO PLB Language Changes' section in the 'PL/B Language Reference' manual. (9.8B)

    SQLIOUSER={svar}

    user name as specified\described by the following:

    1. Sun_Sqlio_Databases schema 'user_name' column.

    2. PLB_SQLIO_USER runtime keyword.

    3. The 'SETMODE *SQLTABLEDB' keyword under the Note (3). (9.8B)

    SUNDMSTATE={nvar}

    state flags that define the current SUNDM child thread execution options as described below. This option only returns data when a AFILE, FILE, or IFILE is opened as a managed file. Otherwise, the returned value is always zero. (9.0F) Prior to version 9.2, this keyword was SUNDMSTATE.

    TREELEVEL={nvar}

    current tree level of an ISAM file. If {file} is not an IFILE, 65535 is returned.

    TXTNAME={svar}

    qualified text file name currently associated with an AAM, ISI, TXT file.

    VIEW={svarlit}

    current view name that has been assigned to an AFILE, IFILE, or FILE variable. If there is no view name assigned to the file variable, the {svar} variable is set to NULL.

     

  6. The following keywords may be used in association with a COMFILE that has been opened to a socket:

    7.  

    Keyword

    Returns the ...

    REMOTEIP={svar}

    remote IP dotted address for the socket.

    LOCALIP={svar}

    local IP dotted address for the socket. If the COMFILE was created and no IP address was specified on the COMOPEN, an IP address string of 0.0.0.0 is returned. An IP address string of 0.0.0.0 indicates that a socket is listening on all interfaces on the current host.

    LOCALPORT={nvar}

    current port number assigned to the socket.

    SOCKHANDLE={nvar}

    current socket handle.

    COMHANDLE={nvar | ivar}

    Windows file handle created by COMOPEN for a Windows local communications port. The returned file handle performs specialized operations using WINAPI.

     

  7. The following keywords may be used in association with a DBFILE (9.0E):

    8.  

    Keyword

    Returns the ...

    DBHOST={svar}

    host database source used by the driver when making a connection. The {svar} can be NULL.

    DBUSER={svar}

    user named used by the database driver when making a connection. The {svar} can be NULL.

    DBPASS={svar}

    the password used by the database driver when making a connection. The {svar} can be NULL.

    DBCONN={svar}

    additional login information used by the database driver when making a connection. The {svar} can be NULL.

    DBEXT={svar}

    extension data used by the database driver when making a connection. The {svar} can be NULL.

    DBDIALOG={svar}

    connection string returned a database driver when a database DIALOG selects the database source. The {svar} can be NULL when a DIALOG interface is not used.

     

  8. The following keywords may be used in association with a PFILE that has been opened:

    9.  

    Keyword

    Returns ...

    ATTRIBUTES={nvar | ivar}

    the printer attributes (see below)

    COMMENT={svar}

    a string that provides a brief description of the printer.

    DATATYPE={svar}

    a string that specifies the data type used to record the print job.

    DRIVERNAME={svar}

    a string that specifies the name of the printer driver.

    LOCATION={svar}

    a string that specifies the physical location of the printer (for example, "Bldg. 38, Room 1164").

    PDFNAME={svar}

    the file name used for the PDF output of the PFILE. (9.6B)

    PORTNAME={svar}

    a string that identifies the port(s) that transmit data to a printer. If a printer is connected to more than one port, the name of each port is separated by a comma (for example, "LPT1:,LPT2:,LPT3).

    PRINTNAME={svar}

    a string that specifies the name of the printer.

    PROCESSOR={svar}

    string that specifies the name of the print processor.

    PRTBINCOUNT={nvar}

    the number of bins available for a Windows printer that is opened using a PFILE. (9.6)

    PRTBINTYPES={svar}

    the bin types that are available for a Windows printer that is opened using a PFILE. The types are packed into the {svar} variable as decimal numbers that are separated with a semicolon (;) character. (9.6)

    PRTBINNAMES={svar}

    the bin names that are available for a Windows printer that is opened using a PFILE. The bin names are packed into the {svar} variable with a semicolor (;) character separating each bin name.(9.6)

    SERVERNAME={svar}

    a string identifying the server that controls the printer. If this string is NULL, the printer is controlled locally.

    SHARENAME={svar}

    a string that identifies the share name for the pinter.

     

  9. The ATTRIBUTES parameter can be any reasonable combination of bits from the following table:

    10.  

    Attribute

    Value

    Meaning

    PRINTER_ATTRIBUTE_QUEUED

    0x1

    If set, the printer spools and starts printing after the last page is spooled.

    PRINTER_ATTRIBUTE_DIRECT

    0x2

    Job is sent directly to the printer (it is not spooled). If not set, the printer spools and prints while spooling.

    PRINTER_ATTRIBUTE_DEFAULT

    0x4

    Indicates the printer is the default printer in the system.

    PRINTER_ATTRIBUTE_SHARED

    0x8

    Printer is shared.

    PRINTER_ATTRIBUTE_NETWORK

    0x10

    Printer is a network printer connection.

    PRINTER_ATTRIBUTE_HIDDEN

    0x20

    Reserved.

    PRINTER_ATTRIBUTE_LOCAL

    0x40

    Printer is a local printer.

    PRINTER_ATTRIBUTE_ENABLE_DEVQ

    0x80

    If set, DevQueryPrint is called. DevQueryPrint may fail if the document and printer setups do not match. Setting this flag holds mismatched documents in the queue.

    PRINTER_ATTRIBUTE_KEEPPRINTEDJOBS

    0x100

    If set, jobs are kept after they are printed. If unset, jobs are deleted

    PRINTER_ATTRIBUTE_DO_COMPLETE_FIRST

    0x200

    If set and printer is set for print-while-spooling, any jobs that have completed spooling are scheduled to print before jobs that have not completed spooling.

    PRINTER_ATTRIBUTE_WORK_OFFLINE

    0x400

    Indicates whether the printer is currently connected. If the printer is not currently connected, print jobs will continue to spool.

    PRINTER_ATTRIBUTE_ENABLE_BIDI

    0x800

    Indicates whether bi-directional communications are enabled for the printer.

    PRINTER_ATTRIBUTE_RAW_ONLY

    0x1000

    Indicates that only raw data type print jobs can be spooled.

    PRINTER_ATTRIBUTE_PUBLISHED

    0x2000

    Windows 2000 or later: Indicates whether the printer is published in the directory service.

     

  10. The FILEFORMAT value contains bits with the following meaning:

    11.  

    Value

    Meaning ...

    0x1

    IFILE

    0x2

    AFILE

    0x10

    version 9.0x format

    0x20

    version 8.7x format

    0x40

    The ISI file format supports file larger than 4GB.

     

  11. The EORTYPE is one of the following values:

    12.  

    Value

    The end of record type is ...

    0

    Carriage return

    1

    Carriage return, line feed

    2

    Line feed

    3

    Line feed, carriage return

     

  12. The open Mode is one of the following values:

    13.  

    Value

    The open mode is ...

    0

    Not defined

    1

    Exclusive

    2

    Share

    3

    Read

    4

    SHARENF

     

  13. The NAMETYPE is one of the following values:

    14.  

    Value

    The file type is ...

    1

    MS-DOS

    2

    RMS

    3

    Linux

     

  14. The ISIFLAGS value is a bit mask defined as follows:

    15.  

    Value

    Meaning ...

    0x1

    Key is forced to be upper case.

    0x2

    The text file is indexed for variable length records.

    0x4

    Duplicates keys are not allowed.

    0x8

    The text file allows compressed records.

    0x10

    The text file is indexed with no EOR used.

    0x20

    All records are written into the text file at the end of file.

    0x40

    Size of the end of record: 00 = 1 byte, 40 = 2 bytes

    0xC0

    EOR type mask defined as the follow values:

    0x0 - EOR is one byte consisting of a carriage return.

    0x80 - EOR is one byte consisting of a line feed.

    0x40 - EOR is two bytes consisting of a carriage return and a line feed.

    0xC0 - EOR is two bytes consisting of a line feed and a carriage return.

    0x100

    ISI is indexed for large file support.

    0x600

    ISI sector sizes being used. (Reserved)

    0x1800

    Platform mask that identifies a specific OS type that can be used when opening an ISI file.

    0x800 - Only allow ISI to be opened by a Windows runtime.

    0x1000 - Only allow ISI to be opened by a Linux runtime.

     

  15. The SUNDMSTATE value is a bit mask defined as follows:

    16.  

    Value

    SUNDM Data Manager ...

    0x1

    uses message compression.

    0x2

    use messages encryption.

    0x4

    requires user logon.

    0x10

    supports IFILE prepare instructions where a command line is stored into the ISI header.

    0x40

    supports ADMIN operations.

    0x80

    supports client keep-alive messages.

    0x100

    does not return control to a client runtime until a FILEPI locks all the files in its file list.

    0x200

    provides client reconnection recovery.

    0x400

    allows long receive timeouts for the client program opening managed files.

    0x800

    allows GETFILE DBFILE data retrieval.

    0x1000

    supports enhanced GETFILE data retrieval.

     

  16. The DMISCONNECTED value is defined as follows:

    17.  

    Value

    The file variable is ...

    0

    not connected to a SUNDM data manager.

    1

    connected to a SUNDM data manager and the socket connection is good.

    2

    connected to a SUNDM data manager and the socket connection is closed.

    3

    the socket for the file variable causes a socket error. The SUNDM data manager connection should be re-established by re-opening the file(s). (10.2)

     

  17. Only the following keyword is associated with a FILELIST:

    18.  

    Keyword

    Returns the ...

    FILELISTNAMES={svar}

    'NAME={filename}' keyword that can be used for an AFILE/IFILE file declaration. The data returned in the {svar} is a semi-colon delimited string that has the filename information for the AFILE/IFILE declarations in the FILELIST. The FILELISTNAMES information can be retrieved when the AFILE/IFILE file variables are closed or opened.

     

    Example:

     

    FL FILELIST

    A IFILE NAME="c:\path\name.isi"

    B AFILE NAME="c:\path\name.aam"

    C IFILE

    X IFILE NAME="c:\path\namex.isi"

             FILELISTEND

    .

             GETFILE FL, FILELISTNAMES=S$CMDLIN

     

    The expected result of data in S$CMDLIN is "c:\path\name.isi;c:\path\name.aam;;c:\path\namex.isi;"

 

  1. For each file variable declaration found in a FILELIST, there is a single ';' character inserted into the output data after a NAME keyword filename. A semicolon (;) delimiter character is always inserted into the output data even where the NAME keyword is not specified for a file variable in a FILELIST. Therefore, the returned data string always contains data regardless of whether the NAME keywords are specified. The user application can use the OCCURS instruction to count the number of semicolon characters. This gives the number of file variables in the FILELIST variable.

  2. The GETFILE instruction supports Windows Drive Substitution. (9.6)

  3. Additional information regarding this instruction is available from PDF GETFILE and GETINFO Notes.

  4. When retrieving the following GETFILE keywords for a file variable opened for SQLIO operations, the returned names are described as follows: (9.8B)

    5.  

    Instruction

    Returns the ...

    GETFILE TXTNAME

    schema data depending on whether a AFILE, FILE, or IFILE file variable is being used. The returned name is described as follows:

     

    FILE - The TXTNAME name is retrieved from the 'Sun_Sqlio_File' schema data under the 'file_name' column.

     

    IFILE - The TXTNAME name is retrieved from the 'Sun_Sqlio_IFile' schema data under the 'file_name' column.

     

    AFILE - The TXTNAME name is retrieved from the 'Sun_Sqlio_AFile' schema data under the 'file_name' column.

    GETFILE ISINAME

    schema data as specified by the 'Sun_Sqlio_IFile' data under the 'name' column which is used for a file variable opened for SQLIO operations.

     GETFILE AAMNAME

    schema data as specified by the 'Sun_Sqlio_AFile' data under the 'name' column which is used for a file variable opened for SQLIO operations.

     

  5. GETFILE using the ADMIN variable type is ONLY used to determine whether the ADMIN variable is currently opened or not by setting the ZERO flag appropriately. The ADMIN is opened using the ADMLOGON instruction.

 

 

See Also: Example Code, PREPDEFAULT, Disk I/O Instructions

 


PL/B Language Reference FPOSITC GETFNAME