Boolean AND operator

and: is used to apply a bitwise Boolean 'and' operation to the two integer arguments.

Length of binary file buffer in words (p)

This is the number of words reserved in the QX array as buffer space for each binary file. The length of this buffer should be defined to be optimal for the local mass storage device. It should not be less than 500 words, and must be (in terms of bytes) at least as large as bdfchr:.

Record length in characters of a direct-access binary file (n)

This is the record length in characters (bytes) that is specified in the Fortran OPEN statement when a direct-access binary file is opened.

Close an input binary file (n)

Read a binary file (n)

This macro is used in all bdf processing.

Open an input binary file (n)

Write a binary file (n)

bdfwrite: is used in all bdf processes.

Open an output binary file (n)

Number of bits remaining in word

bitlen: is used to fill high-order bits in intpak: commands. If $1 is 0 the bitlen: has the value mxbtwd:. See GENSIN and SIMPEL for applications.

Filename of the CIF mapping file

The name of the file which is used by CIFIO to map the archive file data items to the IUCr CIF data names as defined in the CIF Dictionary. This file is supplied as the file cifmap but this definition must make the file accessible to all Xtal users in any directory.

Filename of the CIF request file

The name of the file which contains the standard requested data items to be extracted by CIFIO from an Xtal archive file. These data items are placed into a CIF for transmission to other sites or for electronic submission for publication. This file is supplied as the file cifreq. It is normally made accessible to all Xtal users in any directory.

Close a direct-access file

Close a sequential formatted file

Close line output punch file (n)

This macro should only be used in nucleus routines, except in very special circumstances.

Compare packed real words

This macro compares of two real words that contain packed integer data. For example, it is used for sorting and matching of packed hkl data. Any of the standard Fortran 'dot' relational operators may be used but without the surrounding dots. An example follows where the value of hkl has been packed into words in an array, A, and a search for identical values of hkl in the array B is to be made.

N=0#                           Reset the coincidence count
DO I=1,MA; DO J=1,MB#          Loop over arrays A and B
compakwd:(A(I),EQ,B(J),N=N+1)# Compare and count

Compare character strings

compchar: uses a nucleus routine to compare a character string with a sequence of character strings. It is used extensively in Xtal programs. An example application of compchar: was given in the line input description earlier.

Compiler type (n)

compiler: is the 3-6 character code that identifies the compiler type for the selection of the machine-specific macros from the XMACRO file. The codes listed at the start of XMACRO specify the existing macro definitions.

Copy a complete binary file

copybdf: is used to execute the copybdf command entered by a user. This causes a binary file to be copied from one filename to another.

Copy logical records from one binary file to another

Applications of copyfile: have been described earlier. Arguments $3 and $4 are usually expressed as the macro names for the logical record types. Because the numbering of macro names may vary at different sites, the copying of selected logical records must be specified in a general way. A typical sequence might be

copyfile:(1,2,1,decr:(lratom:))#	Copy up to lratom: records
readwpkt:(1,lratom:,NP,IP,2)#	Read & copy lratom: records
copyfile:(1,2,incr:(lratom:),decr:(lrrefl:))#	Copy to lrrefl:

Decode character array CHRIN into real array BUFIN

The application of dcodefld: has been described earlier. dcodefld: converts the input character array CHRIN into field data to be stored into a real array BUFIN. The default mode of conversion is free format but this can be changed by the user using FIELD and ORDER control lines. These lines are described in the User's Manual. A description of the decoded field data in BUFIN was given earlier.

Archive file end-of-file record number

This is a logical record number representing the end of an archive file.

Filename of error message file

The filename of the Xtal system error message file. This file is supplied as the file xerror but its definition must make the file accessible to all Xtal users in all directories.

Define filename construction (n)

This macro is used to construct the filenames of the different devices that it opens. A typical definition is $1//'.'//$2 which results in Xtal file names of the form 'compid.ext'. For machines where the '.' is illegal this could be $1//$2. For machines where the file name cannot exceed six characters this should be set to 'XTL'//$2 or 'FILE'//$2. The total length of the filename string must not exceed ten (10) characters.

Get CPU time in seconds (n)

getcpus: gets the CPU execution time in seconds. Used for elapsed time reports.

Get the date as a character string

getdate: is used to put the date into the TITLE line. DD is numerical day; mmm is the character month and YY is the numerical year (-1900).

Unpack hkl indices from QX array word

gethkl: extracts reflection indices from the packed hkl word in the QX array. This is the packing format used in the bdf record lrrefl:. See program FC for an application of gethkl:.

Get time of day as character string

gettime: returns a character string with the wallclock time in hours, minutes, and seconds. This is used primarily by the nucleus routines.

Word filled with hexadecimal 80 in each byte

Define a full word packed with hexadecimal 80 in each byte. Used by SIMPEL.

Tests for character and number

ifch: is true if $1 is a real number less than the value of voidflg:. $1 is then assumed to contain the packed numbers that point to the character string in CHRIN. ifnm: is true if $1 is a real number greater than voidflg:.

Test for equality

These macros are used to compare two floating-point numbers. They prevent the diagnostic "an attempt to establish exact equality between floating-point number may not be valid". The use of equality relational operators between floating-point numbers is not permitted in Xtal programs. These macros must be used instead. Two typical examples which do not use the optional argument, are:

ifne:(QX(I+3),AMAX) BMAX=QX(I+3)#	Reset the maximum
ifeq:(QX(J+5),0.) NEXT#	 	Skip if zero

When the default error value (small:) is inapproriate, a third argument can be used:

TEST=AVEAB*1.E(-decr:(mxsgfp:))#	Redefine resolution
ifeq:(A,B,TEST) NEXT#		Skip if A=B

Test for voidflg:

ifvo: tests if a real number is the same value as a voidflg:. ifnv: tests if it is not.

Increment QX array index

A description of the application of incrqx: has been given previously. Note that incrqx: must be applied carefully. If $2 is specified carelessly or inconsistently two serious problems can occur. One is an attempt to store data in QX beyond the currently defined limit, and the other is the zeroing of data that has already been stored. Both can lead to very mysterious errors.

Process bdf directory packet

indexpkt: calls a nucleus routine to extract and insert item identification information from/into the directory packet of directory-type logical records (read the Archive files section for a description of these records). indexpkt: returns relative pointers to items in the packet which are input or to be output. If requested, indexpkt: prepares and writes the directory packet in an output file. A description of how indexpkt: is applied has been given earlier which should be read as an overview of bdf input/output. Using the same format as previously, let us consider the different functions of indexpkt:

	indexpkt:(NFIL, LREC, PSIZ, PAKPT, MFIL, KEY, WANT, RELPT)

The first five arguments of indexpkt: are identical in function to the readwpkt: macro. The sixth argument (KEY) is a four-element integer array that contains the signals that control the function of indexpkt:. The nature of these controls is detailed below. The seventh argument (WANT) is an integer array containing the identification numbers of items to read or written from/into this logical record. The order that ID numbers are stored in WANT is determined by the functions of KEY(1) to KEY(3). The order of the relative pointers returned in RELPT is determined by the value of KEY(4). For most applications indexpkt: is used in update mode (KEY(4)=0) and the pointers in RELPT are returned in the same order as the ID numbers in WANT.

The items to be identified in the directory packet are divided into three groups depending on whether they are mandatory input, optional input or to be added/deleted. If an item belongs to more than one group, the ID number for that item must appear more than once in the WANT array.

The ID numbers for all mandatory input items are stored in WANT first, followed by the ID numbers for all the optional input items and, if an output file is to be written, the ID numbers for any items to be added to or deleted from the output file. The same ID numbers can be in all groups. This makes possible their application as input data and subsequent removal from the output file.

KEY(1) is set as the number of mandatory input items in the WANT array. KEY(2) is the number of items in the WANT array that belong to both the mandatory input and optional input groups. KEY(3) is the total number of items in all three groups. KEY(4) is a signal to indicate whether indexpkt: is to operate in the update or the archive mode.

indexpkt: 1 to KEY(1) Mandatory input items

Mandatory input is defined as information which must be in the designated logical record of NFIL if the calculation which follows is to be carried out. The ID numbers are stored in WANT(I), I=1 to KEY(1). If any of the mandatory input items are missing from the input file, the index I of the last missing item is returned in KEY(4) as a negative number. It is up to the programmer to decide whether a different strategy may be employed or the run should be terminated.

indexpkt: KEY(1)+1 to KEY(2) Optional input items

Optional input is information which may be used if it is in the file, but it is not essential. These ID numbers are stored in WANT(I), I=KEY(1)+1 to KEY(2). The returned value of KEY(4) is not affected by missing items in this category, but the appropriate value of RELPT is returned as zero.

indexpkt: KEY(2)+1 to KEY(3) Added/deleted items

If an output file MFIL is to be written, the ID numbers for items to be added to or deleted from this file are entered in the WANT array after the mandatory and optional input. That is, they are stored in WANT(I), I=KEY(2)+1 to KEY(3). The way in which the relative pointers are returned for these items is determined by the mode signal set in KEY(4).

Update mode KEY(4)=0 allows the modification of existing items or appends new items to the output packet. No deletions are permitted in this mode. New ID numbers are added to the end of the directory packet, existing ID numbers remain unchanged. RELPT is returned with the relative pointers in the order of the WANT list. The value of KEY(4) is returned as the output packet size. This mode must be used with logical records where each packet is for a different dataset.

Archive mode KEY(4)=1 allows for the addition and/or deletion of items to/from the output packet. In this mode, all of the ID numbers in WANT(I), I=KEY(2)+1 to KEY(3), are first deleted from the input packet (if they exist) and the positive ID numbers are added to the end of the compressed packet for output. Items that are not to be output are entered with negative ID numbers. For non-existing items in WANT(I), I=KEY(2)+1 to KEY(3), the relative pointer is returned as 10000. In this mode, RELPT is returned as a pushed-down list of sorted (ascending magnitude) relative pointers to the "delete" items only. This speeds up the subsequent data packet transfers. The value of KEY(4) is returned as the output packet size.

This mode is used when specific items in the input packet must not be transferred directly to the output packet. This is a requirement in programs that are applied repetitively. For instance, a structure factor or least-squares program reads the lrrefl: packet that may contain previous values for the items FCAL, ACAL, and BCAL. These values should not transferred to the output packet since new or different values for these items will be added during the calculation. If current and past values of such items exist on the same bdf, there could be serious problems with later calculations (e.g. a Fourier calculation).

To enable the rapid transfer of items from the input to the output packets during the calculation, indexpkt: returns RELPT values for only the items that are listed in WANT and are present in the incoming packets. These have been sorted in sequential order so that RELPT can be used as a 'no-copy' list which is checked as items are being copied from the input to the output packet. When the sequential order of an item in the input packet matches that of the RELPT array (between KEY(2)+1 to KEY(3)) it is not copied and the RELPT array index is incremented. Subsequently, items identified by positive ID numbers in WANT are appended to the end of the output packet.

Warning: If the WANT array contains the same ID number repeated consecutively, as used for example to point to all of the words a large character string data item (e.g. an atom label), the RELPT array will be returned containing pointers to the consecutive words. That is, if WANT contains the IDN's 11 11 11 11, RELPT will be returned with 5 6 7 8 if the first IDN 11 is located in word 5. This is correct but a problem can occur if by chance two non-character IDN's are loaded into WANT consecutively. indexpkt: will automatically return the pointers as consecutive words, and this may not be what is needed. This is an usual circumstance but some care is required on the part of the programmer.

Examples of indexpkt:

Update mode: KEY(4)=0

The update mode is used in the GENEV program. An input lrrefl: must contain the packed hkl, sin(theta)/lambda, the packed m/e/r word (See the Archive Files section of the Reference Manual). It may contain interpolated scattering factors, normalized structure factor 1 and 2, the relative intensity, and the sigma(I). An abbreviated input directory packet for such a lrrefl: record is represented below.

The minimum amount of information required by GENEV is hkl, m/e/r, and I. If interpolated scattering factors and sigma(I) are available, they will be used. At the end of the calculation, the two normalized structure factors and a group structure factor will be put in the output file. From this information the WANT and KEY arrays may be set. (It is not necessary to zero the RELPT array since this is done automatically.)

Input Directory Packet

Output Directory Packet

Note that KEY(4) is returned as the expanded packet size of 10. In this example ID numbers in WANT(I), I=7 to 9, are checked against the input directory. Those present are transferred, those not are appended to an expanded packet.

Archive mode: KEY(4)=1

Here is a similar example to the one above, using the archive mode.

Input Directory Packet

Output Directory Packet

Note that all ID numbers in the archive list are 'deleted' from the input directory and only the positive ID numbers are added to the output directory. RELPT(I), I=6 to 10, contains the relative packet pointers of the items present in the input packet (with any missing input items flagged with 10000), sorted into the order encountered on input. The sorted order is to optimize the subsequent copying of packet items. An ID number (such as 1600) may appear both in the search lists and in the archive list. Note that the negative ID numbers are not to be output. Positive ID numbers 1600 (which is repositioned) and 1604 (which is added as a new item) are to be output.

A good example of how to apply the archive mode is provided in subroutines FC04 and FC05 of the FC program. Other examples may be found in CRYLSQ, LSLS, etc.

Initialize system common variables

This macro is used to call the Xtal system initialization routine. It is called only once.

Initialize program scheduling

This macro is used to call the system scheduling routine. This macro is used in the nucleus root program and, at the start of each run, and after the conclusion of each calculation, it reports the start and the finish of each calculation.

Inquire if a named file exists (n)

inquirefile: tests whether a particular file with the name $3, whose filename has been stored in the system variable FILENM($1), exists in the user's directory. If it exists $2 is returned as 1; if it does not $2 is returned as 0. This macro is used to test for the existence of files which are to be read, and for the existence of the master file.

Inquire if a named file is open (n)

inquireunit: tests if a particular file with the name $2 is currently open. If it is, $1 is returned as the unit number; if it is not $1 is returned as 0.

Pack integer into real word

An example follows:

	INTPAK:(IH,QX(IR+I),10,20)#

Insert the integer IH into the real word QX(IR+I) in the bit slice 20 to 29 (right to left).

Unpack integer from real word

An example follows:

	INTUNPAK:(QX(IPT+1),INT,5,12)#

Extract bits 5 to 16 (right to left) from a real variable QX(IPT+1) and transfer to the integer variable INT. The variable INT is zeroed before the bits are transferred.

Device numbers of the first and second auxiliary direct access files

ioda1: and ioda2: are the elements in the IOUNIT array used to store the auxiliary direct-access file device numbers. They are initialised to the device numbers unitda1. and unitda2:.

Device number of error message file

ioerr: is the element in the IOUNIT array used to store the error message file device number. It is initialised to the value uniterr:.

Device numbers of sequential formatted files

iofm0:, iofm1: and iofm2: are the elements in the IOUNIT array used to store the auxiliary formatted sequential access file device numbers. They are initialised to the device numbers unitfm0:, unitfm1: and unitfm2: respectively.

Device number of standard line input file

ioinp: is the element in the IOUNIT array used to store the standard line input device number. It is initialised to the device number unitinp:. This device number is automatically interchanged with the system variable IOIN2 when an end-of-file is encountered by readline:.

Device number of line output punch file

iopch: is the element in the IOUNIT array used to store the 'punch' line output device number. It is initialised to the device number unitpch:.

Device number of standard line output file

ioprt: is the element in the IOUNIT array used to store the standard line output device number. It is initialised to the device number unitprt:. The application of ioprt: depends on the definition of the macro writeline:.

Error and exit routine

iquit: calls the nucleus routine to handle an error condition designated by the error code XXYYZZ, and, in the case of an input line error, the field number. XX is the program code (eg AA) ; YY is the subroutine number; and ZZ is a number to identify the location of the error in the subroutine. This code is used to search the error file ioerr: for the appropriate error message. If the $1 is entered as -XXYYZZ, control will be returned to the calling program after the error message has been output; otherwise the Xtal run will terminate.

Examine and strip atom label

label: serves a number of functions. They are:

Real number limit for tests (p)

large: is used to distinguish a word containing a real number (i.e. one with a floating-point format) from a packed-integer number. The usual definition of large: is 1.0E+mxsgfp:

End of system macros (n)

lastnucmac: is the last system macro definition stored in XMACRO.

Physical line inputter (n)

linein: is the primitive line reading macro. It is not to be confused with readline: which uses linein: to do the actual line inputting. $1 is usually defined as ioinp:, $2 as CHRIN; $3 is the length of the input line up to the last non-blank character (the value of the system variable CHRMAX) and $4 signals with a non-zero value that a physical end-of-file has been encountered.

Physical line outputter (n)

lineout: is used to output lines to device ioprt: and it is active conditional on the value of prtstat:. It is used by writeline:. The first argument for lineout: is tested against prtstat: to determine if the line is to be output. That is, the output occurs only if $1 is less than or equal to prtstat:. lineout: is most often written from buffer CHROT.

Start re-entrant line input stream (n)

Temporarily divert the standard user line input control to another named file. When the end of this file is reached return to inputting fro the standard line input file.

System startup instructions (n)

localstart: is used to execute any initial startup instructions prior to system execution. It is the first code encountered in the main program.

System shutdown instructions (n)

This macro is used to allow for an orderly exit from the operating system. For most operating systems this will be a null macro.

Convert character string to lower case characters

locase: converts the first $3 characters in $1 to lower case and places them in $2.

Logical record numbers

These macros define the logical record numbers of the macros lr****: for the types permitted in a standard bdf. Refer to the Archive Contents Section for a detailed description of each record, and to the file XMACRO for actual definitions.

Default level of master file support (p)

masterfile: signals whether the master archive file is to be used. That is, whether the nucleus saves the latest archive binary file (aa1 or aa2) as an ASCII achive file aaa. If master file support is turned off (masterfile: set to no:), the current archive bdf is not stored as or generated from a master file. When turned on (master: set to yes:), the current archive bdf is used to produce a master file with the filename extension aaa at the end of an Xtal run, and generated from this file at the start of an Xtal run. Note that the master file switch may be changed by enetering the master line.

Maximum QX array dimension (n)

memmax: defines the maximum permitted index for the QX array. Its definition depends on the position of the common QXDATA in memory. The value of this macro is stored in the system variable MAXMEM.

Minimum floating-point number magnitude (p)

mnfpnbr: is the magnitude of the minimum floating-point number of the given machine. Numbers less than this value will constitute a floating-point underflow on the machine.

Transfer character string

movechar: is used to transfer characters between arrays of type-CHARACTER. Arrays must be declared using chardata: or string: macros. KEY=1 is used for inserting a single character such as blank or - into a string of characters in another array.

Move character string to real array

movector: is used to transfer a character string from a type-CHARACTER array to type-REAL array. This MUST be used when storing character information in the QX array. If KEY is non-zero and the first character of the source array is a blank character, the destination array is filled with $5 blank characters.

Move packed real word

movepakwd: is used to transfer a single packed word from one real variable to another, without any floating-point normalization. In other words, the bit pattern of the transferred word will not be changed even if it does not conform to the format of the floating-point processor. This macro may be used by movereal: in order to protect packed and character data in real arrays.

For example, to transfer the packed hkl word from a bdf buffer to a local variable, apply

			movepakwd:(QX(IP+1),PAKHKL)#

Move real arrays containing real, character and packed words

movereal: is used to transfer strings of real words which may contain real, character or packed integer information, without altering the bit patterns (i.e., no renormalization).

Move character string from real to character arrays

movertoc: is used to transfer a character string from a type-REAL array to a type- CHARACTER array. This MUST be used when transfering characters from the QX array.

Number of bits in a character (p)

Number of bits in a real word (p)

Note that no bit packing in real words is permitted in Xtal beyond 32 bits.

Number of characters in an input line image (p)

Default number of characters in a print line (p)

mxchln: is the default value placed in prtcmax:. prtcmax: may be changed by the user with a RESET line but may never exceed mxcout:.

Number of characters in a real word (p)

Maximum number of characters permitted on a print line (p)

This is the maximum value possible that prtcmax: may be set to.

Maximum number of input fields (p)

mxfdim: is the maximum number of input fields to be allowed on an input line. This defines the size of the field buffer array BUFIN used by the field decode subroutine.

Maximum number of output fields (p)

mxfdln: sets the maximum number of fields in the output buffer BUFOT which is commonly used in conjunction with ncodefld:.

Maximum number of lines per page (p)

This is the value stored initially in prtlmax: but may be changed by the user with the reset line.

Number of significant decimal digits in a floating-point mantissa (p)

Number of characters per inch across printer (p)

nchin: is the number of characters per inch on a print line. This value is stored in prtcpin:. prtcpin: may be changed with the reset line.

Encode (format) real data to character representation

ncodefld: encodes floating-point numbers into character representations according to the format codes stored in $4. It is a function corresponding to FORMAT operations in Fortran. The use of ncodefld: causes a call to the nucleus subroutine AA03. Read the preceding chapter for a general description of the application of ncodefld: and writeline:. Because ncodefld: only encodes reals, integer numbers must be stored as a real before application. The array BUFOT is commonly (but not necessarily) used as the output field buffer.

The format codes CCCLLDT. are defined as follows

Format types T

Note that for format types 1, 2 and 3 voidflg: numbers are output according to the value of the system variable PRVOID. If PRVOID is -1 voidflg: is output as a number; if it is 0 voidflg: is output as blank and if it is 1 voidflg: is output as the character string @@@@.

Application of ncodefld:

Consider the application of the array of format control words corresponding to the conventional Fortran FORMAT statement:

		100 FORMAT(10X,I5,2F12.6,E15.7)

This format would be coded in Xtal as:

		realdata:(FMT,[150513.,271262.,391262.,541571])#

or as

		realdata:(FMT,[1513.,1262.,1262.,1571])#

In the first statement the column positions are stated explicitly in the second they are not. Note that the second format cannot be used if the data was not being output equentially from left to right. The following statements encode four numbers in the BUFOT array into the character buffer CHROT; and then write CHROT to the line output device ioprt:.

		ncodefld:(BUFOT,1,CHROT,FMT,4)#  Encode the output data
		writeline:(1,0,0,1,3)#           Write encoded data

Force new page on ioprt: (n)

Default number of lines per inch down the print page (p)

nliin: is the default number of lines per inch down the printer page which is stored in prtlpin: by the initialization routine. prtlpin: may be changed with the RESET line.

Open a direct-access file

opendac: is used to open a file with fixed record lengths which can be accessed using direct-access Fortran reads and writes. If the filename is entered as a blank string ' ', the file will be opened according to filename:.

Open a formatted file

openfile: is used to open a character file which will be accessed by Fortran formatted reads and writes. If the filename is entered as a blank string ' ', the file will be opened according to filename:.

Open the auxiliary line output (punch) file (n)

openpch: opens the standard 'punch' file, the device number of which is stored in iopch:. Note that this macro may only be used in the nucleus.

Number of Ozy messages allowed (n)

The error message file (supplied as errmes on the distribution tape) contains a number of "Ozy" messages that are ouput following an error diagnostic message. The value of oznum: is set in XMACRO to the maximum number of Ozy messages on this file. If the user does not wish these messages to be printed, oznum: should be set to zero.

File name of protein dictionary

Protein dictionary used by PRECED to set parameters for CEDAR

File name of the profile data base file

Profile database opened by the programs CHARGE and PARTN. This file is supplied in XLIB as the access profdb. profile: must be defined so that this file is accessible to all users, independent of account or directory.

File name of protein restraint database

Protein restraint database used by PROTIN to set up restraints for later least-squares refinement of protein fragments.

Current maximum width of printed line

prtcmax: is the IOSPEC array element that stores the maximum number of characters for the line output unit ioprt:. The default value is mxchln:, but this can be changed during execution using the reset line.

Current number of characters per inch accross the printed line

prtcpin: is the IOSPEC array element that stores the number of characters per inch for a line of the output unit ioprt:. The default value is nchin:, but this can be changed during execution using the reset line.

Current maximum lines per printed page

prtlmax: is the IOSPEC array element that stores the current maximum number of lines per page of the output unit ioprt:. The default is mxlnpg:, but this may be reset during execution using a reset line.

Current number of lines per inch down the printed page

prtlpin: is the IOSPEC array element that stores the lines per inch for a page of the output unit ioprt:. The default value is nliin:, but this may be changed during execution using the reset line.

Current line printer priority

prtstat: is the priority limit for the line output device ioprt:. The value of prtstat: is initialised to 3 (normal) but may be modified during execution using the reset line. This sets the current maximum line priority (as assigned to each writeline:) that will be output.

Allocate memory to QX array

qxmemory: is used to reset the maximum current index of the QX array that may be accessed. If the index limit is increased the added QX words are zeroed. The value of $1 may not exceed memmax:. See applications of qxmemory: at the start of this section.

Read a direct-access record

readdac: reads a specific direct-access record designated by the number $3 into the variable array $4. If $2 is entered as a format statement (note the comma inside the square brackets), the file is assumed to be a direct-access formatted file. If $2 is void or an END statement, the file is assumed to be a unformatted file. The input item names are surrounded by square brackets to form a single argument $4. Examples of formatted and unformatted direct-access files follow

NREC=NREC+1#                           Incr record pointer
readdac:(2,['(10i5)',],NREC,IBUF)#     Read formatted record nrec
.............
readdac:(unitdac:,[END=100,],23,JBUF)# Read unformatted record 23
.............
100 CONTINUE

Read a formatted record

readfile: reads a single record according to the format defined in $2. The input item names are surrounded by square brackets to form a single argument $4.

Read line from ioin1: and identify

readline: invokes the nucleus routine to read an input line into the character buffer CHRIP. This line is copied into CHRIN and all characters converted to upper case. The input line identifier is then checked against $1 and the system variable LINID set according to the sequential number of the matched code. If no match is found and $2 is a positive number, a quit is called and an error message is generated.

If $2 is a negative integer, a failure to find a match leads to a return to the calling program with no error message generated. Under this condition the value of LINID is set to zero. The next call to readline: will bypass the input step and reprocess the current input line. In this way multiple lists of line identities may be checked by means of readline:. Note that when defining the list of line identifer codes using chardata:, the macro datastuff: automatically produces the character count of this string. An example of the application of readline: is given at the start of this section.

Read bdf packet

readwpkt: reads a bdf as packets of data. If $5 is non-zero readwpkt: also writes the data from the same buffer to the designated bdf. readwpkt: provides a pointer to the first word-1 in each packet for the designated logical record type. When the last packet has been exceeded this pointer is returned as 0. A general description of readwpkt: and application are given in the preceding chapter. See typical applications of readwpkt:. in the program FC.

Rewind bdf

rewindbdf: rewinds the designated bdf without closing the file. This cannot be used for line files.

Real number limit for tests (p)

small: is used to check for equality between floating-point numbers. This number is based on mxsgfp: and is used in expressions such as the following:

	IF(ABS(A-B)>small:) A=B#

If the quantities A and B are not numbers near 1.00000 then this test may fail. For instance if A and B are two values nearly equal but greater than 1.0E+(mxsgfp:) they may not be perceived as equal. Similarly if A and B are less than 1.0E-(mxsgfp:) they may not always be perceived as being equal. See also the macros ifeq: and ifne:.

Get character string limits in CHRIP and CHRIN arrays

stringlim: extracts from the field buffer BUFIN the string limits (first character and last character +1) of the designated field number. This macro is only used for fields that represent alphanumeric character strings. The definition of a character string, and the application of stringlim:, have been given at the start of this section.

Decimal representation of the horizontal tab character

Device number of first binary data file (p)

unitbdf: defines the device number assigned to the first binary. This number is stored in IOUNIT(1). The file numbers of all other binary files are assigned sequentially from this number and stored in array elements IOUNIT(2) to IOUNIT(8).

Default device numbers of the auxiliary direct-access files (n)

These are the default device numbers of the unformatted or formatted auxiliary direct-access files. These numbers are stored in ioda1: and ioda2:.

Default device number of the error message file (n)

uniterr: is the default device number for the error file errfile:.

Default device numbers of the auxiliary sequential formatted files (n)

These are the default device numbers of the auxiliary formatted line files.

Default device number of standard line input unit (n)

Where possible the default device number should match the 'stdin' assignation for the machine. unitinp: is stored in ioinp:.

Default device number of auxiliary line output (punch) unit (n)

This is the default device number of an auxiliary line output file. unitpch is stored in iopch:.

Default device number of standard line output unit (n)

Where possible the default device number should match the 'stdout' assignation for the machine. unitiprt: is stored in ioprt:.

Convert character string to upper case

upcase: converts the first $3 characters in $1 to upper case and places them in $2.

Date of last source update (p,n)

update: sets the date of the current update. This is printed at the top of each page.

Version number of current system (p,n)

version: is the number printed in the title line at the top of each page.

Flag to signal field is void

This macro sets the value which is stored in the floating-point input buffer array, BUFIN, as a signal that an input field is void. The usual definition is -4.0E+20. Numbers with values more negative than this number are used to store information about character strings in the input fields; numbers more positive than this number are treated as "reals". The value of this number may not be changed. The macro is supplied to allow testing of BUFIN values to find void, numeric, and alphabetic fields. See also ifvo: and ifnv: for methods of testing for void fields.

Write direct-access record

writedac: writes a single direct-access record $3 containing items $4. If $2 is a format statement (note the comma inside the square brackets), the file is considered to be formatted. If $2 is void the file is considered to binary. The output item names are surrounded by square brackets to form a single argument $4. Examples of formatted and binary writedac: applications follow

NREC=NREC+1#	                       Increment record counter
writedac:(2,['(I10,30A2)',],NREC,[MM,BUF])# Formatted record
writedac:(unitdac:,,23,BUF)#                Binary record 23

Write to formatted sequential file

writefmt: writes the single record designated in $3 according to the format defined in $2. The output item names are surrounded by square brackets to form a single argument $3.

Write output lines

writeline: outputs the character buffer CHROT, and/or a supplementary character string designated by $2, to the line file ioprt:. Which lines are output is specified with the function KEY. Whether a particular writeline: outputs a line at all is determined by the value of $5 and the current print priority limit prtstat:. writeline: is also responsible for all pagination processes. An application of writeline: has been at the start of this section.

writeline: function KEY

The integer value of KEY specifies the function of writeline:. Its use in conjunction with the system variables LINRM and LINCT enables the programmer to control the output of header lines and pagination. LINCT contains a count of the number of lines remaining on a page. This is automatically updated by writeline:. LINRM is the number of lines that must remain on the current page for writeline: to output a line to this page. This variable is set by the programmer to ensure that there is sufficient space on a page for a particular set of output lines. Note that if the KEY value is negative, the header line will not be output at the start of a new page during the invocation of the writeline:.

KEY

Note that if KEY is supplied as a negative number all functions will remain the same except that the header line will be suppressed if pagination occurs during output of designated lines.

writeline: print priorities

The print priority in $5 is used as a signal to writeline: of the relative importance of each line of output. The following priority levels are recognised.

The current priority status prtstat: is always compared with the value of $5. If $5<=prtstat: the line(s) are output to device ioprt: Check the definitions of these macros in this chapter.

writeline: pagination

The macro nextpage: is used to force a new page but this should NOT be used by programmers. The programmer forces a new page by setting LINCT=0 prior to the application of writeline: and thus ensures that writeline: performs all of the necessary pagination functions (e.g. outputting title line, etc.). If the programmer wishes to prevent automatic pagination, say, for purposes of printing a Fourier map or plotting a figure, the variable LINCT can be set to a large number for the duration of this sequence of writeline:s. It is, however, important to set LINCT to zero again after this sequence is complete.

writeline: Examples

Output a message

chardata:(X01, SORT IS COMPLETE)#
...................
writeline:(0,X01,NX01,3,3)#	Output char string X01 only

Output a number

ncodefld:(X,1,CHROT,131242.,1)#	Format X as F12.4, col.13
writeline:(0,0,0,1,3)#		Output value of X

Output data within a header array

chardata:(X03, VALUE OF X IS )#
....................
ncodefld:(X,1,X03,271242.,1)#	Format X into X03
writeline:(0,X03,NX03,3,3)#	Output char string X03 only

Output data list preceded by header

chardata:(X001,[ H K L SIN(T)/L INTENSITY])#
realdata:(FMT,[40413.,80413.,120413.,220852.,341131.])#
.......................
LINRM=3#				Need 3 lines to start list
REPEAT#					Loop over reflection data
$(# 					>>>>>>>>>>>>>>>>>>>>>>>>>>>> 4
.......................
DO I=1,3;BUFOT(I)=FLOAT(IH(I))#	Store hkl in op buffer
BUFOT(4)=STOL#			Store sin theta/lambda
BUFOT(5)=RELI#			Store I(rel)
ncodefld:(BUFOT,1,CHROT,FMT,5)#	Format stored items
writeline:(0,X001,NX001,1,3)#	Print hkl, s, I(rel)
.......................
$)#					<<<<<<<<<<<<<<<<<<<<<<<<<<<< 4

Write line to pch file

writepch: is similar to lineout: except that it is applied to output lines to a 'punch' file iopch: (which has the default device number unitpch:). Note that writepch: automatically opens iopch: on the first write, and the nucleus automatically closes iopch: at the end of a run.

Write binary file packet

writepkt: writes packets of the specified logical record type to the binary file $1. writepkt: returns the QX index of the first word-1 in the packet. This pointer is used to store the output data in the packet region of the QX array. The physical buffer in the QX array in which the logical records and packets reside is defined within the limits of IOMARK($1)+1 and IOMARK($1)+bdfbuf:. See the preceding chapter for a general description of writeline: and its application. Some simple examples are also available in the program FC. It should be noted that it is unnecessary to write logical record 1(the history record) of the bdf as this is done automatically with the first application of writepkt:.

Boolean exclusive OR operator

xor: is used to apply a bitwise exclusive OR operation to the two integer arguments.