2.23: TQGTRH

TOCGroup 1TQCLOSTQGSUGroup 2A-ZGroup 1

GET-TRANSPARENT-FILE-HEADER-INFO

Use TQGTRH to retrieve information stored in the header of a transparent file.

Added for ChemApp version 4.0.0

Synopsis

FORTRAN: CALL TQGTRH(VER,NWP,VNW,NRP,VNR,DTC,DTE,ID,USR,REM,NOERR)

C: tqgtrh(&ver,nwp,&vnw,nrp,&vnr,&dtc,&dte,id,usr,rem,&noerr);

Pascal: tqgtrh(ver,nwp,vnw,nrp,vnr,dtc,dte,id,usr,rem,noerr);

Basic: Call tqgtrh(ver,nwp,vnw,nrp,vnr,dtc,dte,id,usr,rem,noerr)


Name Type Value set on call or returned
VER INTEGER Returns the version number of the transparent file header format
NWP CHARACTER Returns the name of the program which wrote the data-file (40 chars)
VNW Array of 3 of
INTEGER
Returns the version number of the program which wrote the data-file
NRP CHARACTER Returns the ID(s) of the programs which are permitted to read the data-file (40 chars)
VNR Array of 3 of
INTEGER
Returns the minimum version number of the reading program necessary to load the data-file
DTC Array of 6 of
INTEGER
Returns the creation date of the data-file
DTE Array of 6 of
INTEGER
Retuns the expiry date of the data-file
ID CHARACTER Returns the user ID(s) of the license holder(s) who are permitted to read this data-file (255 chars)
USR CHARACTER Returns the name(s) of the license holder(s) who are permitted to read this data-file (80 chars)
REM CHARACTER Returns the remark (80 chars)
NOERR INTEGER Returns an error number

Note that the lengths of the various character strings returned by TQGTRH are greater than regular ChemApp character strings, which is 24. It needs to be made sure that the character variables in the application program which are used with TQGTRH are of sufficient length. Their required lengths are indicated in the table above.

As mentioned in Chapter 1.11, transparent data-files all have a header which precedes the actual thermochemical data. This header contains a number of fields which can be retrieved using TQGTRH:

VER
This single integer indicates the version number of the transparent file header format. It can usually be ignored by the programmer.

NWP
This string (40 characters long) contains the name of the program that wrote the data-file. It can consist of one of the 4-letter identifiers used in the NRP field below, or a real name like "FactSage".

VNW
This array of 3 integers is used to pass the version number of the program that wrote the data-file. In the case of FactSage 5.0, the three integers in this array would be 5, 0, and 0.

NRP
This string (40 characters long) contains one or more program IDs and is used to determine which programs are capable and authorized to read the data-file. The program IDs used are 4-letter mnemonic codes that identify a particular program or library (i.e. ChemApp). For instance, if a data-file is meant to be used with the full version of ChemApp, NRP would be set to CAFU, if it is intended for ChemApp light instead, it would be set to CALI. NRP can also contain more than one program IDs, and also program IDs which contain wildcards, in order to make the data-file available to more than one kind of program or library.

This field can usually be ignored by the programmer, as ChemApp itself determines whether it is able and authorized to read a particular data-file.

VNR
If applicable, this array of 3 integers contains the required minimum version number of the program that the data-file is intended for. If, for instance, a data-file contains thermochemical data for a mixture phase that requires a solution model only present in ChemApp version V3.5.0 and later, the three integers would be 3, 5, and 0. This array can usually be ignored by the programmer, as ChemApp itself determines whether it is able to read the data-file based on this version number. If the first integer has a value of -1, NRP can be ignored altogether.

DTC
This array of 6 integers contains the creation date and time of the data-file. The 6 integers indicate the year, month, day, hour, minute, and second of the creation of the data-file. Note that this information is independent of the particular time stamp of the data-file as reported by the operating system.

DTE
The 6 integers in this array (same format as DTC) indicate the expiry date of the data-file.

ID
This string (255 characters long) contains one or more user IDs and is used to determine whether ChemApp is authorized to load the data-file. There are three typical scenarios as to what ID contains and how it is interpreted:

  1. The most common case is that a user has a license for a program like FactSage, which can be used to create transparent data-files. When he creates such a data-file, his user ID, which is stored in the FactSage program, is transferred to the ID field of the transparent file. If this user also has a license for ChemApp, he can read this transparent data-file with all programs he creates using his version of ChemApp. The same transparent data-file on the other hand cannot be read by a ChemApp version which operates under a different license, and thus a different user id. Likewise, he will normally be unable to read a transparent data-file created by a FactSage user with a different user ID.

  2. For users who do not create their own transparent data-files using FactSage or similar programs, but need to be supplied with a transparent customised data-file for use with ChemApp, GTT-Technologies will create such a file, in which case ID will contain the user ID of the ChemApp customer.

  3. As with the NRP field, this field may also contain several user IDs and user IDs with wildcards. This is used to grant a group of users who have different IDs access to the same particular data-file. This will also enable a group of users, who might work jointly on data assessment, to create transparent data-files and share them within the group.

USR
This string (80 characters long) contains the user name associated with the user ID stored in the previous field (ID). Other than THFID, it is not used to for authorisation checks, but only for information purposes.

REM
This string (80 characters long) contains text that the program writing the transparent data-file may use to store any kind of remark.

Note that in order for TQGTRH to be able to access and retrieve the various transparent file header fields, a transparent data-file needs to be read successfully first.

See also

TQOPNT, TQRCST, Chapter 1.11

Examples

See TQRCST


ChemApp Programmer's Manual, Edition 3.6© GTT-Technologies, 2003