ZSPC Statements

ZSPC statements are used in writing Mentor or Survent utilities or applications to get more information on data files, DB items, or other system uses, such as date/time formatting. Both Survent and Mentor use ZSPC statements to get immediate access to system information.

The syntax for ZSPC statements is:

!ZSPC,<subtype>,<suboption>,[return code],[col.wid1],[col.wid2],...,[col.widn]
  • [return code] is a one column wide field to hold the return code
  • [col.wid1] is a field holding (or to hold) the information for Argument 1
  • [col.wid2] is a field holding (or to hold) the information for Argument 2, etc.

NOTE: For all subtypes, a return code of D means that there is no data case to deal with and a return code of Z means there were zero arguments.

ASCII_FILE_IO

Shortform: ZSPC, ASCIIFILEIO

The ASCII_FILE_IO subtype reads or writes a line of an ASCII file.

NOTE: This is the most frequently used subtype.

The syntax for a ZSPC question subtype ASCII_FILE_IO is:

ZSPC,ASCII_FILE_IO,<suboption>,[return code],[filename],[data area]

[Return code]

  • BLANK operation successful
  • A – Not two arguments
  • B – Bad subtype
  • N – Nothing to read (nothing in the file or past end of file)
  • 0 – File open failure 

The [filename] is the data location where the name of the file to read has been put.

The [data area] is the data location to read. Exactly one ASCII line will be read, and data area will be cleared beyond the end of the line. A maximum of 950 bytes can be read.

Valid Suboptions: 

  • READ_ASCII_LINE
    • Reads a line of data from an ASCII file.
  • WRITE_ASCII_LINE
    • Writes a line of data to an ASCII file.
    • The return code, filename and data area are the same as the READ_ASCII_LINE suboption.
  • READ_SEQUENTIAL_ASCII_LINE
    • Reads a line of data sequentially from an ASCII file.
    • The return code, filename and data area the same as the READ_ASCII_LINE suboption.
    • The first ZSPC,ASCII_FILE_IO,READ_SEQUENTIAL_ASCII_LINE will read the first record in the data file.
      • The second ZSPC,ASCII_FILE_IO,READ_SEQUENTIAL_ASCII_LINE will read the second record in the data file, etc.
  • READ_TEXT_ANSWER
    • Reads a line of data from an ASCII file into a TEXT question.
    • The return code and filename are the same as the READ_ASCII_LINE suboption except the data area must be a TEXT question.
  • WRITE_TEXT_ANSWER
    • Writes a line of data from a TEXT question to an ASCII file.
    • The return code and filename are the same as the READ_ASCII_LINE suboption except the data area must be a TEXT question.

EXAMPLE:

{ RETURNCODE:  .1
!VARIABLE,USE_PREVIOUS_ANSWER }

{ FILE_NAME: .100
xxxxx
!SPECIAL,SAVE_TEXT_LINE_TO_DATA }

{ DATA_LOC: .50
!VARIABLE,USE_PREVIOUS_ANSWER }

{ ZSPC11_1:
!ZSPC,ASCII_FILE_IO,READ_ASCII_LINE,RETURNCODE,FILE_NAME,DATA_LOC }

{ ZSPC11_6:
!ZSPC,ASCII_FILE_IO,READ_SEQUENTIAL_ASCII_LINE,RETURNCODE,FILE_NAME,DATA_LOC }

Other Subtypes

DB_FILE_IO

Shortform: ZSPC,DBIO

The DB_FILE_IO subtype stores or retrieves items in a Survox DB file.

The syntax for a ZSPC question subtype DB_FILE_IO is:

ZSPC,DB_FILE_IO,<suboption>,[return code],[argument1],[argument2],[argument3]

[Return code]

  • A – Not 2 or 3 arguments
    • 1 – Length of argument is one more than 16
    • 3 – Argument 3 is bad file name
  • E – Error in DBstore routine
  • 0 – All OK

[Argument 1] is the name of the DB item to store (the maximum number of characters in a DB item name is 24).

[Argument 2] is the name of the file to store (or write out) or the location in the currently open data file.

[Argument 3] is optional and is the name of the DB file to store to; the default is the current DB file opened READ_WRITE. You may say “LOCAL” for local DB file.

Valid Suboptions: 

  • STORE_ASCII_DB_ITEM
    • Stores ASCII data from a file into a Survox DB file.
  • STORE_BINARY_DB_ITEM
    • Stores binary data from a data file into a Survox DB file.
  • WRITE_ASCII_DB_ITEM
    • Takes an ASCII DB item and writes it to a new data file.
  • WRITE_BINARY_DB_ITEM
    • Takes a binary DB item and writes it to a new data file.

EXAMPLE:

{ ZIPCODE:
What zip code do you want to look up:
!VARIABLE,NUMERIC_ONLY,5,5 }

{!COMMENT
Store the name of the DBfile into the Data }

{ ZIPDB:
USZIP
!SPC, 9 }

{ RETURNCODE: HIDE
!VARIABLE }

{ ZIPDATA: HIDE
!VARIABLE }

{ ZSPC3_1:
!ZSPC,DB_FILE_IO,STORE_ASCII_DB_ITEM,RETURNCODE,ZIPCODE,ZIPDATA,ZIPDB }

DB_FILE_ITEM_INFO

Shortform: ZSPC,DBINFO

The DB_FILE_ITEM_INFO subtype checks for information related to a DB item.

The syntax for a ZSPC question subtype DB_FILE_ITEM_INFO is:

ZSPC,DB_FILE_ITEM_INFO,<suboption>,[return code],[argument1.#]

[Return code]

  • A Not 1 argument
  • W Width not 8 or 16 columns
    • 0 Doesn’t exist
    • 1 Number (NUMERIC question)
    • 2 Categories (FIELD question)
    • 3 Vector (or multi-column number)
    • 4 String (VARIABLE question)
    • 5 Table
    • 6 DB spec file
    • 7 Exists, but is something else altogether

[Argument 1] is the DB name to check and will have a length of 8 or 16 depending on the suboption below.

Valid Suboptions:

  • SHORT_DB_ITEM_NAME
    • Checks on items with an 8 wide DB name.
  • LONG_DB_ITEM_NAME
    • Checks on items with a 16 wide DB name.

QUERY

The QUERY subtype returns information on data files and other system elements.

The syntax for a ZSPC question subtype QUERY is:

ZSPC,QUERY,<suboption>,[return code],[argument1],[argument2],...,[argumentn]

Valid Suboptions: 

  • CFMC_TRIPLE_AMPERSAND_TEXT
    • Returns the information off the &&&qfilename command line.
    • This lets you say something like ‘&&&HELP INPUT’ and have the help system start out at the INPUT block.

The syntax for a ZSPC,QUERY question suboption CFMC_TRIPLE_AMPERSAND_TEXT is:

ZSPC,QUERY,CFMC_TRIPLE_AMPERSAND_TEXT,[return code],[argument1]

[Return code]

  • A – more than 1 argument
    • 1 – Argument 1 not long enough to hold text
  • N – not in &&& command
  • Y – all OK

[Argument 1] is the text that follows the &&&qfilename. The leading spaces are taken out of the returned text. 

 

  • CORE_AVAILABLE
    • Returns the amount of available core memory space.

The syntax for a ZSPC,QUERY question suboption CORE_AVAILABLE is:

ZSPC,QUERY,CORE_AVAILABLE,[return code],[argument1.5]

[Argument 1] is the location for amount of available core. Width must be five. 

 

  • CURRENT_CFMC_COMMAND_BLOCK
    • Returns the tilde (~) block of Mentor that the user is in.

The syntax for a ZSPC,QUERY question suboption CURRENT_CFMC_COMMAND_BLOCK is:

ZSPC,QUERY,CURRENT_CFMC_COMMAND_BLOCK,[return code],[argument1.2]

[Return code]

  • A – more than 1 argument
    • 1 – Argument 1 not 2 columns wide
  • Y – all OK

[Argument 1] is the number of the tilde block currently in:

  • 00 Not in any block
  • 01 DEFINE
  • 02 RESET
  • 03 SORT
  • 04 STOP_WATCH
  • 05 PREPARE
  • 06 SET
  • 07 INPUT
  • 08 CLEANER
  • 09 RESTORE
  • 10 MAKE_ASQ
  • 11 QSP_FILE
  • 12 QFF_FILE
  • 13 ADJUST
  • 14 unused
  • 15 JCD (debugging)
  • 16 PRACTICE
  • 17 unused
  • 18 OUTPUT
  • 19 unused
  • 20 TRANSLATE
  • 21 COPY
  • 22 unused
  • 23 NEXT
  • 24 EXECUTE
  • 25 unused
  • 26 VIEW
  • 27 CLOSE_STUFF
  • 28 INTERVIEW
  • 29 SHOW
  • 30 unused
  • 31 FREQUENCY
  • 32 DROP
  • 33 COMMENT
  • 34 unused
  • 35 unused
  • 36 CY (debugging)
  • 37 unused
  • 38 NEW
  • 39 WRITE_SPECS
  • 40 UPDATE
  • 41 SPEC_RULES

 

  •  DB_ITEM_INFO
    • Checks DB items to see if they exist, and what type of item they are.

The syntax for a ZSPC,QUERY question suboption DB_ITEM_INFO is:

ZSPC,QUERY,DB_ITEM_INFO,[return code],[argument1],[argument2],[argument3]

[Return code]

  • A – More than 3 arguments
    • 1 – Length in Argument 1 more than 16
    • 2 – Length in Argument 2 bad (should be 6-60)
    • 3 – Argument 3 is bad file name
  • F – DB file not defined
  • N – Item not in DB file
  • Y – Item is in DB file

[Argument 1] is the name of the DB item to check; it can be 8 or 16 wide.

[Argument 2] if specified, is where information about the DB item is to be returned. The default is do not return.

Data returned if argument 2 is specified:

type 6 bytes Variable, table, etc.
gloss1 6 bytes If variable, is type of variable (0-9)
gloss2 6 bytes  More info about the item
instance 6 bytes Nth occurrence of this item (if multiple)
entry num 6 bytes This is the directory slot used for this item
byte offset 10 bytes This is the file position of this item
byte count 6 bytes This is the byte length of item as stored
when put 14 bytes This is standard time format when item stored: YYMMDDHHMMWJJJ

[Argument 3] if specified, is the name of the DB file to look in. Default: any open DB file. May be ‘LOCAL’ for the local DB file. 

 

  • FILE_EXISTS
    • Returns whether a file exists, and if it does, it’s fully qualified file name.

It interprets most valid Survox filename specifications; an @name is treated as a DEFINED value, a !name! is treated as a variable set at the operating system level. Caret (^) is treated as a dot (.). Wildcard characters (*,?,#) for multiple file references are not interpreted, since the command only deals with one file at a time.

The syntax for a ZSPC,QUERY question suboption FILE_EXISTS is:

ZSPC,QUERY,FILE_EXISTS,[return code],[argument1],[argument2]

[Return code]

  • A -More than two arguments
  • N – File not found
  • Y – File found

[Argument 1] is the name of the file to return information on and can include the Survox characters described above. You may include directory/group information, or if not, the program assumes the file is in the current work area.

[Argument 2] returns the fully qualified filename if used (not required).

EXAMPLE:

{ ENTERFILENAME:
Enter a filename to look for:
!VARIABLE,,40 }

{ RETURNCODE: .1 HIDE
!VARIABLE }

{ ZSPC2_5:
!ZSPC,QUERY,FILE_EXISTS,RETURNCODE,ENTERFILENAME }

{ RETURN:
Return Code is \|RETURNCODE, try again?
!FIELD
1 Retry
2 Quit }

{!IF RETURN(1)
!RESET ENTERFILENAME }
  • LAST_CFMC_ERROR_CODE
    • Returns the last error code seen (i.e. the number you see on error messages such as:
(ERROR #2640) expected ~INPUT keyword
(ASCII=#, STOP_AFTER=#, SELECT=, etc.)

In this case, the ZSPC,QUERY,LAST_CFMC_ERROR_CODE would return the number “2640”.

The syntax for a ZSPC,QUERY question suboption LAST_CFMC_ERROR_CODE is:

ZSPC,QUERY,LAST_CFMC_ERROR_CODE,[return code],[argument1.5]

[Return code]

  • A – Not 1 argument
    • 1 – Width not 5
  • 0 – Value of c->errors is in location

[Argument 1] is where to return the error code, and must have a width of 5.

 

  • NEXT_CFMC_TEMP_FILE_NAME
    • Returns the name of the next temporary file to be made by the program.

The syntax for a ZSPC,QUERY question suboption NEXT_CFMC_TEMP_FILE_NAME is:

ZSPC,QUERY,NEXT_CFMC_TEMP_FILE_NAME,[return code],[argument1.8]

Temporary file names have the syntax ‘TE######’ where ###### are sequential numbers from 1 to n for each file made.

[Return code]

  • A – Not 1 argument
    • 1 – Width not 8
  • 0 – Temporary name is in the location

[Argument 1] is where the next temporary name will be returned with a width of 8. 

 

  • PRINTER_PORT_STATUS
    • Checks printer ports in DOS or UNIX.

The syntax for a ZSPC,QUERY question suboption PRINTER_PORT_STATUS is:

ZSPC,QUERY,PRINTER_PORT_STATUS,[return code]

There are no arguments.

[Return code]

  • A – more than 0 arguments
  • N – Printer not found
  • Y – Printer found online
    • O – Printer found offline
    • P – Printer found out of paper

 

  •  TR_FILE_CASE_ID
    • Opens a Survox TR file and checks whether a particular data case exists in it.

The syntax for a ZSPC,QUERY question suboption TR_FILE_CASE_ID is:

ZSPC,QUERY,TR_FILE_CASE_ID,[return code],[argument1],[argument2]

[Return code]

  • A – More than two arguments
    • 1 – Case ID length in Argument 1 is more than 10
    • 2 – Argument 2 has bad data file name
  • B – BINARY input data file
  • D – DTA type input data file
  • F – ASCII input data file
  • I – No input data file and no Argument 2
  • J – Joined files, cannot use
  • N – Case not found
  • O – Cannot open TR file named
  • P – Phantom file, no case ID
  • S – SWAP-BINARY input data file
  • Y – Case found

[Argument 1] is the case ID you want to check.

[Argument 2] is optional and, if specified, indicates the name of the TR file to be checked. If argument 2 is not specified then default to the input TR file.

 

  • TR_FILE_INFO
    • Opens a Survox TR file and returns detailed information about it.

The syntax for a ZSPC,QUERY question suboption TR_FILE_INFO is:

ZSPC,QUERY,TR_FILE_INFO,[return code],[argument1],[argument2]

[Return code]

  • A – More than 2 arguments
  • B – BINARY input data file
  • D – DTA type input data file
  • F – ASCII input data file
  • I – No input file opened
    • 1 – Argument 1 not 5 to 50 columns
    • 2 – Argument 2 had a bad file name
  • O – Can’t open file
  • P – PHANTOM file
  • S – SWAP-BINARY input data file
  • Y – Got file

[Argument 1] is the location for return information. Length controls how much information to get. Can be from 5 to 50 long, depending on information wanted.

Return information:

Item/Order to get Data Type Length Position
Case length # 5 1-5
Number of cases # 7 6-12
Number of deleted cases # 7 13-19
TR file type (0=standard, 1= indexed) # 1 20
Maximum number of cases (approx.) only if indexed # 7 21-27
Duplicates only if indexed Y=Yes, N=No A 1 28
Data file comment A 22 29-50

 [Argument 2] is the name of the TR file to get. The TR part of the name is not required. It defaults to the currently open TR file.