Altadata user guide

Being a guide to the commands available in Altadata, and a chance to use frames to actually enhance something.

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.

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.

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.

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.

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

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

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

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.

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:

( 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

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.

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.

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.

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.

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:

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

Parameter 2 is only used when parameter 1 is fieldname.

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:

Parameter 2 is only used when parameter 1 is fieldname.

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.

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:

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.

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.

OWNER

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

SET membership is also checked.

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.

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.

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.

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

Allowable operators which may be used with IF specifications are:

• EQ or =
• GT or >
• LT or <
• GE or >=
• LE or <=
• NE or /=
• BEGINS or BE
• CONTAINS or CO
• INCLUDES or IN

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:

STORE recordname,S
A;BCDE;123;FGHIJ;456789;E

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!

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.

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.

( This parameter is purely cosmetic, and is ignored )

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.

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.