Altadata user guide

Compiled with enormous help from Altadata's own online help by Mike Fleming

  1. INDEX
  2. COMMANDS
  3. LOOKING & LISTING RECORDS
  4. STORING RECORDS
  5. MODIFYING RECORDS
  6. USING RECMAN FILES
  7. ERROR HANDLING
  8. COMMAND SYNTAX

1 INDEX

DescriptionReferences
*** 4.2
ABN 2.6, 4.3, 5.2
ALPHABETIC 4.3
AREA 8.13, 8.23
ASSIGN 8.1
B (BINARY) 8.30
BACKWARD QUESTIONMARK 8.19, 8.20
BLOB 3.2, 4.3
BUFFER 8.2
C (CHARACTERS) 3.2, 5.3, 8.14, 8.19, 8.20
CALC 8.3
CLOSE 4.5, 6.1, 8.4, 8.10
COMMA 2.3
COMMANDS 8
CONNECT 8.5
CONTROL CHARACTERS 8.14
CONTROL STREAM 2.1, 2.3, 6.2, 7.1, 8.34
CURRENCIES 6.4, 8.6, 8.8, 8.11, 8.25
CURRENT 8.6
DATABASE KEY 3.2, 3.3, 3.4, 8.7
DBKEY 8.7
DEFAULT 4.3, 8.30
DISCONNECT 8.8
DUPLICATE 4.7, 8.9
DUPLICATE KEYS 8.3
E 4.3, 5.2, 8.12, 8.14
EDITING 3.5
END 6.2, 8.10
END OF FILE 6.3
END OF SET 3.5
ERASE 8.11
ERRORS 7.0, 7.1, 7.2
EXAMPLES 2.3, 8.14
EXTRACT 4.5, 6.5, 8.12
FIELD NAME 8.14, 8.22
FIELD VALUE 8.14, 8.22
FIELDS 3.4, 4.3, 5.3
FILLER 3.4
FIRST 8.13
FORMAT 3.5, 8.14
GROUP 3.4
HELP 2.4, 8.15
HEXADECIMAL 3.3
IF 8.29
INFORMATION 8.16
INTERACTIVE 2.6, 4.3, 5.2, 6.2, 8.33
KEY 8.3, 8.7, 8.17
LAST 8.18
LAST ACCESSED 7.1, 8.6, 8.16
LINE 8.7
LINE PRINTER 3.2, 3.3, 3.4
LIST 3.0, 3.1, 3.2, 3.3, 3.4, 3.5, 8.19
LOOK 3.0, 3.1, 3.2, 3.3, 3.4, 3.5, 8.20
MAC 2.1
MACRO 2.4, 8.21
MODIFY 5.0, 5.1, 5.2, 5.3, 5.4, 8.22
N (NATURAL) 4.2, 8.30
NESTING 2.4, 2.5, 8.28
NEXT 8.23
NUMERIC 4.3
OPEN 6.1, 8.24
OPTIONAL 8.8
OWNER 8.5, 8.8, 8.11, 8.18, 8.25
PACKED DECIMAL 4.4
PAGE 8.3, 8.7
PARAMETERS 2.6
PICTURE 3.4, 4.4
POINTERS 8.26
PRIOR 8.27
R (REPORT) 3.5, 8.14, 8.19, 8.20
RECMAN (FILES) 2.1, 4.5, 6.0, 6.1, 6.2, 6.3, 6.4, 8.4, 8.16, 8.24
RECORDNAME 3.2, 3.3, 3.4
REPEAT 2.5, 4.2, 8.28
ROLLBACK 8.10
S (SERIAL) 4.4
S (SKIP) 4.3
SELECT 8.29
STORE 2.1, 4.0, 4.1, 4.2, 4.3, 4.4, 4.5, 6.3, 8.30
SUBSCRIPTING 5.2
SYNTAX 2.3, 3.5, 5.2, 8.31
TERMINAL 6.2
TOTAL 8.32
TRAINING 2.6, 8.33
TRUNCATION 5.3
USE 6.2, 8.34
VALIDATION 4.2
VIEW 8.35

2 COMMANDS

2.1 DESCRIPTION

This section describes the use of ALTADATA commands.

Altadata commands carry out several types of function;

Altadata commands are by default accepted from the control stream, that is the terminal in Mac mode, or the job file in Batch mode.

The user may specify at any time that commands are to be read from a previously created Recman file; control is then passed to that file until end of file or an error occurs, at which point control is returned to the control stream.

Command names may be abbreviated to the first 2 characters; parameters if required follow a single space, and are delimited by commas.

A single input from the control stream may be up to 2000 characters long, if entered in natural format, or 2000-(N-1) characters in length, if entered in serial format, where N represents the number of input fields delimited by semi-colons. A single input may consist of any number of commands, each with their associated parameters and each command separated from the next by semi-colons.

Certain commands require additional data that is not supplied via parameters; when this occurs, the user is prompted for the required data and the data is read from the control stream, except for the STORE command where the user has the option to read data from a previously created Recman file.

The maximum record that may be input is 32764 characters.

2.2 LIST OF COMMANDS

ASSIGN END LIST REPEAT
BUFFER ERASE LOOK SELECT
CALC EXTRACT MACRO STORE
CLOSE FIRST MODIFY SYNTAX
CONNECT FORMAT NEXT TOTAL
CURRENT HELP OPEN TRAINING
DBKEY INFORMATION OWNER USE
DISCONNECT KEY POINTERS VIEW
DUPLICATE LAST PRIOR

2.3 COMMAND SYNTAX

The formal command syntax definition is as below.

command1 parameter1[,parameter2.....][;command2......]

  1. Command names may be abbreviated to the first 2 characters.
  2. Commands are separated from parameters by a single space.
  3. Commands are separated from commands by a semi-colon (;).
  4. Parameters are separated from parameters by a comma (,).
  5. A single command may be up to 200 characters long.
  6. A single input may consist of any number of commands.
  7. Separators may be changed by means of the SYNTAX command.

Below are examples of Altadata commands.

CALC
CALC KEY1,RECORDA
CALC KEY1,RECORDA;EXTRACT;ERASE RECORDA
REPEAT 5;NEXT RECORDB,SETZ;MODIFY FIELDS;EXTRACT

Note that the SYNTAX command allows the user to redefine the syntax of ALTADATA commands, for example

The parameter delimiter comma (,) may be changed to any other single printable character.

The control character "S" used to skip fields during the STORE command may be changed to a different value.

The effect of this command is that the user may use a syntax suited to his mode of working, or that does not restrict his input of, for example, field values.

2.4 USER MACROS

If the same construction is used many times during the session it may be defined as a macro command using a 2 character name. Using this name as a command will cause the execution of the complete construction.

Macros may be edited by redefining - i.e. by quoting an existing macro name.

Macros may be parameterised by using Assignments (see ASSIGN) within the construction. When the macro is used values are given to the assignments e.g. KEY = 1234.

The assignments are implicit. The ASSIGN command is not used.

User macro calls may be nested, but a macro may not reference itself.

User macros may be displayed at any time using the HELP command.

2.5 COMMAND REPETITION

A line of commands may be repeated, using the REPEAT command.

The REPEAT command initiates repetition of the commands from the next command on the line to the end of the input.

Repetition continues until failure or until the count (if specified) expires.

Entering more than 1 REPEAT command on an input causes nested repetition.

When repetition is terminated, control passes back to the previous repeat level, or back to the command stream.

2.6 TRAINING MODE

New users to Altadata can, by means of the TRAINING command, switch the terminal into training mode, which causes Altadata to prompt the user for parameter values to commands.

Part of the prompt screen includes a description of the command parameters.

The user may abandon execution of a command in training mode by typing in ABN.

Training mode is of course only available during an interactive session.

3 LOOKING AND LISTING

3.1 DESCRIPTION

Altadata retrieves and updates records on a user's database. Once it has a record, it can be displayed on the terminal screen or job journal, or listed to a listing file.

This can be done explicitly by using the LOOK or LIST command, or default LOOK and LIST may be set to enable Altadata to carry out the required action after each successful retrieval or update. The user has a choice of formats for the display or records.

3.2 CHARACTER FORMAT

The record may be displayed in character format.

All unprintable characters are converted to blobs, or backward question marks for line printer output.

The record is displayed in lines of 80 bytes for video screens, or lines of 132 bytes for line printer output.

The database key of the displayed record and the record name are also displayed.

3.3 HEXADECIMAL FORMAT

The record may be displayed in hexadecimal format.

All characters are converted to a pair of characters in the range 0 - 9, A - F.

The record is displayed in lines of 80 bytes for video screens, or lines of 132 bytes for line printer output.

The database key of the displayed record and the record name are also displayed.

3.4 FIELD FORMAT

The record may be displayed in field format; ie the names and values of individual data items within the record are displayed, one per line.

All fields are converted to displayable characters as specified by their PICTURE clauses.

No value is displayed for group fields.

Fillers are not displayed (by default): the command SYNTAX enables display to occur.

The database key of the displayed record and the record name are also displayed.

3.5 REPORT FORMAT

The record may be displayed in report format; ie values from specified fields, along with literals and printer or screen control characters, are displayed in a user-defined manner.

The format of the display is specified for a record type using the FORMAT command.

When using report format, records which have no defined format are not displayed, or listed.

When using report format, no error message is displayed at end of set condition.

Limited editing of field values may be defined.

4 STORING RECORDS

4.1 DESCRIPTION

Records are stored using the STORE command.

The data to be stored on the database may be read from the command stream or a Recman file.

The data can be supplied in 4 formats:

Fields and Template formats are exclusive to interactive users.

When Altadata is requested to store a record, it is told where the data is coming from, and also the format in which to expect it.

The data can come from the command stream, which may be the terminal or a command file, or from a STORE file, which has been previously opened using the OPEN command.

The data may be supplied in natural format, where each byte is stored as read, in field format, where the interactive user is prompted for values for each data item, in serial format, where a string of values are supplied separated by the STORE/MODIFY separator character, or in template format which is effectively field format input a screenful at a time.

4.2 NATURAL FORMAT

Records may be stored on the database in natural format, where each byte in the input data is stored on the database exactly as read.

One input record is stored as one database record.

If a record consisting of the string *** is detected the record is not stored and an Altadata status is raised. This is to allow input data to be split into batches when using the repetitive storing technique.

No validation is carried out to ensure that the values supplied in the input record are legal for the item descriptions within the record.

4.3 FIELDS FORMAT

Records may be stored on the database in fields format, where the user is prompted with the name of each field or data item within the record, and the value supplied is converted to the appropriate picture.

Fields format is only available to the interactive user.

The user may at any point abandon the store attempt, by typing in ABN.

The user may at any point request default values to be given to the remaining fields, by typing in E (end), or up to a named field, by typing S (skip).

Default values are spaces for all alphabetic fields, and zeroes for all numeric fields.

To store a field in hexadecimal format, supply the value as HEXvalue.

4.4 SERIAL FORMAT

Records may be stored on the database in serial format, where the user supplies the whole record as a series of field values separated by the STORE/MODIFY separator character.

The syntax for serial input is as follows:

fieldvalue1[;fieldvalue2......];E

4.5 STORE FILE

Records may be read from a serial Recman store file, which has been previously created, and opened by the OPEN command.

This option is only available with natural and serial formats.

The store file may have been created during a previous navigation run using the EXTRACT command.

The file may be closed using the CLOSE command, and another opened during the same session.

4.6 TEMPLATE FORMAT

Records may be entered a screen at a time by supplying field values in unprotected areas of a screen template. The template is displayed showing initial values for fields: spaces for alphanumeric fields, zero for numeric fields.

The first field of every screen is an 'Action' field. If this field is left blank, the record buffer is updated with the values supplied and the next screen (if any) displayed.

If set to 'E', the Store is terminated with the values supplied so far (but NOT including those on the current screen) being used to update the record.

If set to 'A', the Store is abandoned with no updates taking place.

4.7 DUPLICATION OF RECORDS

The DUPLICATE command duplicates an existing record and allows editing to take place before storing the new record on the database.

This command is only available for use in Template format. The record to be duplicated must be current and of the same type as the record for duplication before the command is invoked.

5 MODIFYING RECORDS

This chapter is all about modifying records in the user's database.

5.1 DESCRIPTION

Records are modified using the MODIFY command.

The modified record can be accepted in 4 formats:

Field and Template formats are exclusive to interactive users.

In template, character and hexadecimal formats, the old value is displayed prior to accepting the new value.

5.2 FIELDS FORMAT

Records may be modified in fields format, where the interactive user is prompted to supply a set of field-name/field-value pairs.

The syntax for field modify is as below:

field-name=value[;field-name=value....];E

Field-name may be subscripted up to 3 levels.

Input may span over more than 1 input line; modifying is terminated by the E control character.

The user may at any time abandon modification, by typing ABN.

A single field may be modified by supplying a single fieldname=value pair as the first parameter to the MODIFY command.

The value may be specified as a hexadecimal number by using the format:

field-name=HEXvalue

5.3 CHARACTER FORMAT

Records may be modified in character format, where the user supplies the modified record as printable characters, usually using the SOM and the cursor to bracket the display of the old value as displayed on the screen.

Where a byte has been displayed as a reverse question mark, due to it being unprintable, if it is sent back as a reverse questionmark, that byte position in the record is left unchanged.

Any value returned that is longer than the subschema definition for that record type is truncated.

5.4 HEXADECIMAL FORMAT

Records may be modified in hexadecimal format, where the user supplies the modified record as hexadecimal characters, usually using the SOM and the cursor to bracket the display of the old value as displayed on the screen.

If an invalid hexadecimal pair is supplied, the modify is abandoned.

The maximum input size in hexadecimal format is 1000 bytes.

6 RECMAN FILES

6.1 DESCRIPTION

Recman files are used to hold data for the STORE command, commands for the USE command, and are written to by the EXTRACT command.

Recman files are opened by the OPEN command, and closed by the CLOSE command.

Only 1 file of each type may be open at any one time.

6.2 USE FILE

The USE file holds Altadata commands and data.

When opened and given control by the USE command, it is treated as the control stream in all respects.

If an error is detected during execution from a USE file, control is returned to the original control stream.

Interactive options of certain commands may not be used in a USE file ( eg STORE FIELDS, MODIFY FIELDS ).

If the end of the USE file is detected before reaching an END or a USE T (terminal) command, the file is closed and control returns to the original control stream.

6.3 STORE FILE

The STORE file holds data to be stored by the STORE command.

The data may be in Natural or Serial format.

The STORE file must be opened prior to use by the OPEN command.

If the end of the STORE file is detected, the store command will fail.

6.4 EXTRACT FILE

The EXTRACT file is written to by the EXTRACT command.

The current record is by default written to the Extract file by the EXTRACT command.

The command may be qualified by a parameter, FIELDS, SERIAL, FORMAT, or DATA. The FIELDS option causes the current record to be extracted in 'fieldname=value' pairs. The SERIAL option causes the current record to be extracted in Serial format, suitable for re-entry in the same format using the STORE command. FORMAT causes the formatted fields etc of the last accessed formatted record to be output to the extract file. The use of DATA as the parameter initiates a dialogue where the user is invited to enter any data items to be written to the file.

This allows the user to intersperse data with commands, for example, so that it can be used later as a USE file.

The use of any other data as a parameter causes that data to be written to the file.

The extract file must be opened prior to use by the OPEN command.

The extract file may be closed, and reopened as a USE or STORE file in the same session.

6.5 ALTADATA ON RECMAN FILES

Recman files can be processed by Altadata by providing a Cobol module to access the file. If Altadata identifies a record type as belonging to a Recman file rather than an IDMS database, it will call an appropriate access module to read/write the Recman record rather than attempt to access the database.

An IDMS-lookalike record should be entered into the schema source file and GENERATE_ALTADATA run in the usual way. A special 'ACCESS' clause identifies the Cobol access module to be used.

The access module can be generated by calling GENERATE_ACCESS_MODULE. A 'Keyed' access module will support Indexed Sequential and Hashed Random file organisations.

The file must be assigned before running Altadata, specifying the local name to be the same as the record type name (minus hyphens).

For automatically generated access modules, a keyed access module (i.e. where the record description in the schema source file contains at least one KEY clause) will support the following Altadata record access commands:

Alternate keys are also supported by specifying the key name in the KEY command.

7 ERROR HANDLING

7.1 DESCRIPTION

The following occurs on detection of a command or minor database access error:

  1. Execution of the remaining commands in the input line is abandoned.
  2. An error message is generated, and in most cases displayed.
  3. Control is passed back to the previous repeat level or if there is none, the command stream.
  4. Last accessed record set and area are not updated.

The following occurs on detection of a system or major database access error:

  1. A program dump is executed.
  2. The Altadata run is aborted, with a rollback request.
  3. Control is passed back to SCL.

7.2 COMMAND ERRORS

When an Altadata command fails due to a non-database error, an error number in the range

0001 - 0099

is generated.

7.3 DATABASE ERRORS

When an Altadata command fails due to a database error, an error number in the range

nn01 - nn99

(where nn is 01 - 99 depending on the database action being attempted)

is generated.

8 COMMANDS

8.1 ASSIGN

The ASSIGN command allows the user to create a named variable, and assign a value to it.

The variable name may be used in place of a parameter value in any ALTADATA command, preceded by an *.

The length of the assigned name may be up to 8 characters, while the length of the name being replaced may be up to 30.

PARAM DESCRIPTION VALUES DEFAULT
1 variable name any string mandatory
2 value to be assigned any string spaces

8.2 BUFFER

The BUFFER command assigns a dedicated record buffer to a record type, so that individual fields within a record become addressable and may be used instead of parameter values in ALTADATA commands.

The contents of a buffered field are used in place of a parameter value by prefixing the field name by an *.

PARAM DESCRIPTION VALUES DEFAULT
1 buffer number 0 to 4
null
0 (default buffer)
2 record name valid name
null
last accessed

8.3 CALC

The CALC command retrieves a record occurrence from the database by means of the CALC algorithm, which is applied to an in-record key to generate a database page number. If allowed by the schema, records with duplicate keys may exist, and are stored in the same page if possible.

The CALC command is optimised such that duplicate records may be retrieved by simply omitting all parameters.

For IDMSX users, an AREA parameter specifies the area in which the record is to be found.

PARAM DESCRIPTION VALUES DEFAULT
1 CALC key any string
null
duplicates are retrieved
2 record name valid name
null
last accessed
3 area name
( IDMSX only )
valid name value of system variable T, or spaces
4 LOOK option
5 LIST option

8.4 CLOSE

The CLOSE command is used to close a recman file that has been used as a STORE, EXTRACT, LIST or USE file.

If a file of the specified type is already closed, nothing happens.

PARAM DESCRIPTION VALUES DEFAULT
1 Type of file to be closed U ( use )
S ( store )
E ( extract )
L ( list )
mandatory

8.5 CONNECT

The CONNECT command connects a record occurrence to an owner record of a named set. The record must be defined as an optional member of the set, and must not currently be a set member.

The record to be connected must be current of record type, and the prospective owner must be current of its type.

PARAM DESCRIPTION VALUES DEFAULT
1 Record name valid name
null
last accessed
2 Set name valid name
null
last accessed

8.6 CURRENT

The CURRENT command retrieves current record occurrences of a named record, set, or area or moves the contents of a dedicated record buffer into the default buffer.

The name supplied in parameter 1 is inspected, and if it is a valid record,set or area name or dedicated record buffer number the appropriate record is retrieved.

The command fails if there is no current occurrence of the named record set or area.

If parameter 1 is defaulted, the last accessed record is retrieved.

PARAM DESCRIPTION VALUES DEFAULT
1 Record, set or area name or dedicated record buffer number valid name
1 to 4
null
last accessed record
2 LOOK option
3 LIST option

8.7 DBKEY

The DBKEY command retrieves a record from the database by means of its database key. Alternatively, page direct records may be retrieved by quoting a page number rather than a page/line.

On first accessing a PAGE-DIRECT record, all parameters are mandatory. If parameter 3 (Keyvalue) is omitted, and a PAGE-DIRECT record has been retrieved immediately beforehand, an attempt is made to find a duplicate.

The format of the DBKEY parameter is as follows:

pppppppp-lll where

pppppppp is the database page number ( 8 digits )
lll is the database line number ( 3 digits )

This command may also be used to access records from recman files. The database key represents the record's relative position within record-type within the file.

Thus "DB 3,record-type" causes the third record of the declared record type to be returned.

PARAM DESCRIPTION VALUES DEFAULT
1 Database key valid key mandatory
2 Record name valid name
null
record name not checked. Mandatory for PAGE-DIRECT
3 Record key value valid key value if PAGE-DIRECT keyed access not attempted
4 LOOK option
5 LIST option

8.8 DISCONNECT

The DISCONNECT command disconnects a record occurrence from its owner record within a named set.

The record must be defined as an optional member of the set, and the occurrence to be disconnected must be current of that record.

PARAM DESCRIPTION VALUES DEFAULT
1 Record name valid name
null
last accessed
2 Set name valid name
null
last accessed

8.9 DUPLICATE

The DUPLICATE command is used to duplicate existing records. A template is displayed which allows the current record to be edited, if required, prior to storage.

If the record is defined in the Schema file as DIRECT, or PAGE-DIRECT, the user is prompted for the database key :

"Enter Database Key" or "Enter Database Page No."

The record is stored upon completion of input.

PARAM DESCRIPTION VALUES DEFAULT
1 Record name valid name
null
last accessed
2 LOOK option
3 LIST option

8.10 END

The END command has 2 functions. It may be used to terminate a session or to end a success-unit.

Rollback of the database may be requested by parameter for either of these 2 functions.

When this command is used to terminate a session all files open are closed, update and retrieval counts are displayed, and overflow statistics are also indicated if appropriate.

A request to end a success-unit does not result in termination of the session.

PARAM DESCRIPTION VALUES DEFAULT
1 End requirement (1) null
SU, RO
SUCCESS-UNIT
ROLLBACK
null
2 End requirement (2) As above null

8.11 ERASE

The ERASE command is used to erase a record occurrence from the database.

The occurrence must be current of the named record.

The occurrence may not be the owner of any other record occurrences.

The record type must be named.

Note that after a successful erase, there is no current of run unit.

There is no ERASE ALL option for safety reasons. A macro may be used if the facility is needed.

PARAM DESCRIPTION VALUES DEFAULT
1 Record name valid name mandatory

8.12 EXTRACT

The EXTRACT command is used to extract data to a serial EXTRACT file, which has previously been created and opened by the OPEN command.

The data to be written defaults to the contents of the last accessed record, but alien data may also be written by specifying any value other than FORMAT, DATA, FIELDS or SERIAL in parameter 1.

When writing Formatted data, the fields, controls, character strings, etc. of the last record displayed in REPORT mode, are written to the extract file.

When writing serial data the contents of the current record are written in field format with each field delimited by the Store/Modify separator character.

When writing alien data, input is terminated by the command "E".

PARAM DESCRIPTION VALUES DEFAULT
1 specifies what is to be extracted null current record in natural format
SERIAL current record in serial format
FIELDS current record in fields format
FORMAT format definitions
DATA user is prompted for entry of alien data
any other value value is written to the extract file

8.13 FIRST

The FIRST command is used to retrieve the first record in a set or area, or the first record in a record order key.

When the IF function of the SELECT command is in use, the record retrieved will be the first record satisfying the condition, not necessarily the first physical occurrence.

PARAM DESCRIPTION VALUES DEFAULT
1 Record, set or area name valid name
null
last accessed record
2 Set or area name or record-order-keyname valid name
null
last accessed set, area or record-order-keyname
3 LOOK option
4 LIST option

8.14 FORMAT

The FORMAT command is used to define a format or template which is used during REPORT listing, or when the session default is set using the LOOK or LIST commands to RON (report on).

The FORMAT command is called for each record type to be included in the report. The user defines the template with a series of control-char/ value strings, separated by semi-colons ( ; ) and terminated by the control-char 'E'. Control-chars may be qualified by a length value. Below is a list of control characters:

C Character string eg. C20 THIS IS A STRING
H Head of form
L Newline eg. L3 ( 3 newlines )
D Current date ( yyyy/mm/dd )
S Spaces eg. S20 ( 20 spaces )
F Field value eg. F STOCK-ITEM-NAME
PARAM DESCRIPTION VALUES DEFAULT
1 Name that the format is to be associated with valid record
PAGEHEADER
last accessed record

( Note that PAGEHEADER specifies a special format to be used on all page headers unless overridden )

Example:

FORMAT STOCK-RECORD

  H;L3                         head of page and 3 newlines for each rec
  C20 STOCK RECORD ID IS       literal "STOCK RECORD ID IS "
  F STOCK-ITEM-NAME            value of named field
  S3;C15 STOCK QUANTITY        " STOCK QUANTITY "
  F4 STOCK-QTY                 4 chars of named field
  S3;C STOCK VALUE $           " STOCK VALUE $"
  F5.2 STOCK-VAL               7 digs of named field, 2 after dec pt
  E                            end of format

gives

STOCK RECORD ID IS A0015B   STOCK QUANTITY 5000   STOCK VALUE $  358.50

8.15 HELP

The HELP command is used to provide assistance to users of Altadata.

Extensive structured help text is provided to give online information about status messages and command usage, and access to the user guide.

PARAM DESCRIPTION VALUES DEFAULT
1 HELP key command name
user macro name
GUIDE
user guide
error code
page number
null
VARIABLES
VRBL
initial HELP screen is displayed, or further help on the last subject is given

8.16 INFORMATION

The INFORMATION command is used to provide run time information to the user.

The following information is displayed:

  1. The name of the LAST ACCESSED RECORD
  2. The name of the LAST ACCESSED SET
  3. The name of the LAST ACCESSED AREA
  4. The number of retrieval commands successfully executed
  5. The number of update commands successfully executed
  6. LOOK default
  7. LIST default

This command has no parameters.

8.17 KEY

The KEY command retrieves a record occurrence from the database by means of its keyvalue in a sorted set, or by a named CALC key, or by means of its keyvalue in a record-order-key.

If allowed by the schema, records with duplicate keys may exist, and are stored in the same page if possible.

Where records exist in more than one area, an areaname must be supplied as the fourth parameter.

When using recman files, setname is an invalid parameter option.

The KEY command is optimised such that duplicate records may be retrieved by simply omitting all parameters.

PARAM DESCRIPTION VALUES DEFAULT
1 key value any string
null
duplicates are retrieved
2 record name valid name
null
last accessed
3 sorted setname, keyname or record-order-keyname valid name
null
last accessed
4 areaname valid name
null
last accessed

8.18 LAST

The LAST command is used to retrieve the last record in a set or area, or the last record in a record order key.

An occurrence of the owner record of the named set must be current.

When the IF function of the SELECT command is in use, the record retrieved will be the last record satisfying the condition, not necessarily the last physical occurrence.

PARAM DESCRIPTION VALUES DEFAULT
1 Record, set or area name valid name
null
last accessed record
2 Set, area or record-order-keyname valid name
null
last accessed set, area or record-order-keyname
3 LOOK option
4 LIST option

8.19 LIST

The LIST command explicitly lists the current record occurrence to a listing file, in a format defined by parameter 1.

Where the parameter value zON (where z is one of the parameter values below) is used, the default for the session is set to that value, e.g. KON will switch to displaying the database key only for all records.

Where the parameter value OFF is used, the default for the session is set to display neither contents nor key of the record.

The following formats are supported:

C Character All printable characters are listed
X Hexadecimal The record is listed in hexadecimal format
B Both Character and hexadecimal
F Fields Each field is listed together with its value
R Report Listing is in accordance with the FORMAT definition
K Key The database key only is listed

By default LIST is OFF : to turn it on, LIST CON will give a default of character listing, LIST FON for fields, etc.

PARAM DESCRIPTION VALUES DEFAULT
1 The LIST option C (character)
X (hexadecimal)
B (both char & hex)
F (fields)
R (report)
K (database key)
zON where z is one of the above
OFF
field-name
null
current session default
initially nolist
2 Format option C or X F (field format)

Parameter 2 is only used when parameter 1 is fieldname.

8.20 LOOK

The LOOK command explicitly displays the current record occurrence to the terminal, in a format defined by parameter 1.

Where the parameter value zON (where z is one of the parameter values below) is used, the default for the session is set to that value, e.g. KON will switch to displaying the database key only for all records.

Where the parameter value OFF is used, the default for the session is set to display neither contents nor key of the record.

The following formats are supported:

C Character All printable characters are listed
X Hexadecimal The record is listed in hexadecimal format
B Both Character and hexadecimal
F Fields Each field is listed together with its value
R Report Listing is in accordance with the FORMAT definition
K Key The database key only is listed
PARAMDESCRIPTIONVALUESDEFAULT
1 The LIST option C (character)
X (hexadecimal)
B (both char & hex)
F (fields)
R (report)
K (database key)
zON where z is one of the above
OFF
field-name
null
current session default
initially nolist
2 Format option C or X F (field format)

Parameter 2 is only used when parameter 1 is fieldname.

8.21 MACRO

The MACRO command is used to specify, and to name, a sequence of commands which may be executed by reference to the declared name for the duration of the Altadata session.

There is a limit to the number of characters in any macro of 2000 and a limit to the number of macros of 20.

A macro may contain calls to other macros.

PARAM DESCRIPTION VALUES DEFAULT
1 Name that the macro is to be known by any name which does not clash with any ALTADATA command name mandatory

8.22 MODIFY

The MODIFY command is used to change the data contents of the current record occurrrence, in the format defined by parameter 1.

The following formats are supported:

1 C Character. The modified record is accepted in character format.
2 X Hexadecimal. The record is accepted in hexadecimal format.
3 F Fields. The user supplies a series of fieldname=value pairs.
4 T Template. The record is displayed a screen at a time. The user enters field values in unprotected areas on the screen.
5 Fieldname=value
The specified fieldname is modified with no prompting.
PARAM DESCRIPTION VALUES DEFAULT
1 Input format X (hexadecimal)
C (character)
F (fields)
T (template)
zON where z is one of the above
F (field format)
2 LOOK option
3 LIST option

8.23 NEXT

The NEXT command is used to retrieve the next record in a set or area, or from a record order key for which a currency exists.

When the IF function of the SELECT command is in use, the record retrieved will be the next record satisfying the condition, not necessarily the next physical occurrence.

PARAM DESCRIPTION VALUES DEFAULT
1 Record, set or area name valid name
null
last accessed record
2 Set or area name or record-order-keyname valid name
null
last accessed set, area or record-order-keyname
3 LOOK option
4 LIST option

8.24 OPEN

The OPEN command is used to open a recman file to be used as a STORE, EXTRACT, LIST or USE file.

If a file of the specified type is already open, it is closed.

The file may be referred to by a hierarchic or local name.

Altadata will attempt to create any extract file named and will create the list file if it does not already exist.

PARAM DESCRIPTION VALUES DEFAULT
1 Type of file to be opened U (use)
S (store)
E (extract)
L (list)
mandatory
2 The name of the file to be opened valid hierarchic or local name mandatory

8.25 OWNER

The OWNER command is used to retrieve the owner of the current record occurrence within the named set.

SET membership is also checked.

PARAM DESCRIPTION VALUES DEFAULT
1 Set name valid name
null
last accessed
2 LOOK option
3 LIST option

8.26 POINTERS

The POINTERS command displays the values of pointers held in the current record for a named set.

NEXT, PRIOR, and OWNER pointers are displayed if they exist.

PARAM DESCRIPTION VALUES DEFAULT
1 set name valid name
null
last accessed

8.27 PRIOR

The PRIOR command is used to retrieve the record occurrence logically prior to the current record occurrence within the named set, or physically prior within the named area, or the prior occurrence within a record order key for which a currency exists.

When the IF function of the SELECT command is in use, the record retrieved will be the prior record to satisfy the condition, not necessarily the physically prior occurrence.

PARAM DESCRIPTION VALUES DEFAULT
1 record, set or area name valid name
null
last accessed record
2 set or area name or record-order-keyname valid name
null
last accessed set, area or record-order-keyname
3 LOOK option
4 LIST option

8.28 REPEAT

The REPEAT command is used to initiate repetition of a series of commands.

Repetition is initiated for all commands up to the end of the string of commands input.

If more than 1 REPEAT command occurs on a line, repetition is nested. Repetition can be for a fixed count, or until a status is returned. If nesting is in use, termination of a REPEAT due to expiry of count or detection of a status results in a break to the previous repeat level.

PARAM DESCRIPTION VALUES DEFAULT
1 Number of repeats integer
null
until fail

8.29 SELECT

The SELECT command allows the user to specify selection criteria which will govern the way in which Altadata behaves when executing commands.

Following the use of the SELECT command the user is prompted:

ENTER SELECTION FOR recordname

The user enters the required selection. At present there is only one selection. The IF selection:

IF fieldname condition-operator value

A space must exist between the fieldname/condition-operator and between the condition-operator/value.

Only records meeting the specified condition will be retrieved when commands FIRST, LAST, NEXT and PRIOR are used.

Simple conditions may be extended by using the AND operator :

IF fieldname condition-operator value 
AND fieldname condition-operator value

Compound conditions comprise two or more simple or extended conditions, each separated from the previous condition by a semi-colon :

IF fieldname condition-operator value ;
IF fieldname condition-operator value
   AND fieldname condition-operator value ;
IF fieldname condition-operator value
PARAM DESCRIPTION VALUES DEFAULT
1 Record name valid name mandatory

Allowable operators which may be used with IF specifications are:

8.30 STORE

The STORE command is used to store a new record occurrence in the database, in the format defined by parameter 2.

Currencies must exist to all set owners of which set membership of the record to be stored is defined in the Schema as AUTOMATIC.

The records are accepted from the terminal or a store file.

The following formats are supported:

1 N Natural. The record to be stored is accepted in natural format, i.e. each byte is stored as read.
2 F Fields. The user is prompted with field names, to which he assigns a value. He may apply default values by request.
3 T Template. A template containing default values for fields is displayed a screen at a time. The user supplies field values in unprotected areas on the screen.
4 S Serial. The record to be stored is accepted as a string of fields with each field being separated by the Store/Modify separator character. When the record to be stored is director page direct, the key must follow the data record:
STORE recordname,S
A;BCDE;123;FGHIJ;456789;E
PARAM DESCRIPTION VALUES DEFAULT
1 Record name valid name
null
last accessed
2 Input format N ( natural )
F ( fields )
T ( template )
S ( serial )
zON where z is one of the above
F
3 Location of the input T ( terminal )
F ( file )
T
4 Target realm
(IDMSX only)
valid name spaces or the value of system variable T
5 LOOK option

8.31 SYNTAX

The SYNTAX command allows the user to, for the duration of the ALTADATA session, change the control characters and strings which have a special meaning to the syntax analyser.

The command has one parameter and it is only required when elements are being changed individually or in batch mode.

To best understand how to use this command, type in the command SYNTAX, and see what happens. It is self explanatory; just TAB to the field (or fields) you wish to change, change it (or them), and press SEND.

Note that no cross-field validation is carried out; changing both parameter and command delimiters to say, space, may have unusual effects!

PARAM DESCRIPTION VALUES DEFAULT
1 Requirement null
element=value
null; new syntax values are prompted for interactively

Mandatory in batch mode

8.32 TOTAL

The TOTAL command counts and displays the total number of records in a set or area (or index). It also provides a simple analysis of record distribution. This will only occur however if at least one of the members is located at the home page.

Note that when totalling all records in a set, the owner of the set is included in the total.

PARAM DESCRIPTION VALUES DEFAULT
1 Record, set or area name valid name
null
last accessed record
2 set, area name or record-order-keyname valid name
null
last accessed area or record-order-keyname

8.33 TRAINING

The TRAINING command is used to switch training mode on or off.

It is a flip-flop command, ie if training is on, it is switched off, and vice-versa.

The user types in command name only and is then prompted for parameter values.

The MACRO command may be used to establish Macro content but like the REPEAT command may NOT be used as an executable command.

PARAM DESCRIPTION VALUES DEFAULT
1 Training mode required? Y, YES, ON
N, NO, OFF
mode is switched to its opposite state

( This parameter is purely cosmetic, and is ignored )

8.34 USE

The USE command specifies the input location of Altadata commands.

Commands may come from the terminal ( the control stream ) or from a USE file.

The USE file will have previously been created and opened by the OPEN command.

If a status is detected during execution from a USE file, control is returned to the terminal.

PARAM DESCRIPTION VALUES DEFAULT
1 Location of the input T ( terminal )
F ( file )
no change

8.35 VIEW

The VIEW command displays a specified record description, as recorded in the ALTADATASCHEMA file, or the fields constituting a specified logical key of the record type.

If the specified record is current, then it is also displayed to the terminal.

PARAM DESCRIPTION VALUES DEFAULT
1 Record name valid name
null
last accessed
2 Logical keyname valid key name
CALC
null