Chapter V - How to Install and Test NM-TRAN
This chapter describes how to install
NM-TRAN. It is convenient, but not necessary, to work in a
reserved disk area.
UNIX users might work in a dedicated directory called
(say) /export/home/nmvi/tr.
MS-DOS users might work in a dedicated directory
called (say) c:\nmvi\tr.
CMS users can safely work in the same disk area as in
Chapter III because no NM-TRAN subroutine has the same name
as any NONMEM or PREDPP subroutine.
It is assumed that you have already read the source code for NM-TRAN "TRAN" into a disk file. NM-TRAN does not have different single and double precision versions. It is also assumed that you have already read the file SIZES from the NONMEM distribution medium into the directory above the PREDPP directory, as discussed in chapters 2 and 3
This chapter guides you through the following steps.
|
1. |
Separate the file into smaller files (Optional) |
|
2. |
Make any required changes to the source code. |
|
3. |
Compile the subroutines and build an executable version of NM-TRAN. |
|
4. |
Create a simple test case. |
|
5. |
Run the test case. |
NM-TRAN consists of 117 separate subroutines, all of which are used in every run. You may choose at this time to separate the single large NM-TRAN source file into one or more smaller files, for the following reasons:
|
• |
You may have to modify the NM-TRAN source code before compiling it. The single large file may be too large for your system’s editor. |
|
• |
The single large file may be too large for your compiler. |
|
• |
When bugs are found in NM-TRAN, the fixes are described in emails and technical newsletters. You must modify the source code and recompile portions of NM-TRAN. It is faster and less expensive to do this when the file has been separated. |
If you choose to separate the file into separate subroutines, follow the same procedure as in Chapter III. It makes no difference if SEP or SEPG77 is used with NM-TRAN. It is easiest to use whichever was used for NONMEM.
UNIX:
sep < TRAN
|
MS-DOS: |
sep < tran
|
CMS: |
FORTVS SEP FILEDEF 5 DISK TRAN FORTRAN A LOAD SEP ( START LIST FILE ( EXEC RENAME CMS EXEC A TRAN EXEC A TRAN EXEC REN
It makes no difference if SEP or SEPG77 is used with TRAN. It is easiest to use whichever was used for NONMEM.
You now may make certain changes to NM-TRAN source code. None of these are required.
ABLOCK is a FORTRAN block data routine containing file names, characters identifying the level number of NM-TRAN, and other constants.
The following DATA statement stores character strings giving names for eight NM-TRAN output files:
DATA FSTRM,FREPT,FLIB,FDATA,FWORK,FCON,FSUBS,FWARN
X /’FSTREAM’,’FREPORT’,’FLIB’,
X ’FDATA’,’FWORK’,’FCON’,’FSUBS’,’FWARN’/
These are file names for use in FORTRAN OPEN statements. If these names are not acceptable to your operating system, or if other names are preferred, the character values ’FSTREAM’ etc. may be changed. With CTSS on the CRAY, for example, all file names should be changed to lower case: ’fstream’, etc. In VAX VMS, it may be useful to append the characters ".DAT" to all constants, e.g., change ’FSTREAM’ to ’FSTREAM.DAT’. Unit numbers and attributes of all NM-TRAN files are discussed in Section 4. If ’FLIB’ is changed in ABLOCK, it should also be changed in SIZES; see Chapter VI.
FWARN is discussed in Section 1.1.4.
NM-TRAN copies all user-supplied subroutines specified on the NM-TRAN $SUBROUTINE record to file FSUBS, along with any generated subroutines. This makes it easy to compile user-supplied subroutines, generated subroutines, or a combination, with the same operating system command. You may prefer not to do this, either because the subroutine names are included on the $SUBROUTINES record only as documentation, or because the locally-developed linker commands make use of the list of user-supplied subroutines in file FREPORT, or for some other reason. (FREPORT is discussed in Section 3.3.) To suppress this feature, i.e., to prevent NM-TRAN from copying user-supplied code to FSUBS, change TRUE to FALSE in the following DATA statement:
DATA CPYUSR/.TRUE./
Note that if you use the NMLINK6 program on the NONMEM distribution medium, as is done in the UNIX and MS-DOS examples in Chapter VII and Appendices 4 and 5, you must not change the value of CPYUSR; it must remain .TRUE..
The first line of file FREPORT contains characters identifying the version and level numbers of NM-TRAN. In ABLOCK, there is a level number similar to the following†:
DATA LEV/’1.0’/
----------
Changing this number in ABLOCK will never be necessary, but the user may choose to do this in order to establish a record that the bug fixes were implemented. See also Chapter III, Section 2.2.4.
The following DATA statement stores constants related to warning messages:
DATA WU,LONGID,MAXMSG/6,7,20/
NM-TRAN generates various warning messages. These are not fatal, and can be ignored. Here is an example.
(WARNING 1) NM-TRAN INFERS THAT THE DATA ARE SINGLE-SUBJECT.
Constant WU specifies the unit to which warning messages are written. It is set to 6 on the distribution medium. Consequently, both warning messages and error messages are written to standard output. If WU is set to any other value, NM-TRAN opens the unit specified by WU using the filename found in the FWARN constant (above Section 1.1.1 above). This causes warning messages to be written to a different file from that used for the error messages, which are always written to unit 6. WU and FWARN can be used to direct warning messages to (e.g.) a pop-up window in a windowing operating system.
Constant LONGID specifies the maximum number of characters in the ID data item that NM-TRAN will accept without producing a warning. If the number of characters (excluding trailing 0’s) in a value of ID exceeds LONGID, there is a risk that low-order digits will be lost when the value of ID is converted to a single precision floating point number, causing NONMEM to treat the data from two successive subjects as if they arose from the same subject. If single precision floating point numbers occupy more than 4 bytes with a particular computer architecture, the user may choose to increase the value of LONGID to avoid inappropriate warning messages.
Constant MAXMSG specifies the maximum number of warning messages, data warning messages, and data error messages that will be printed by NM-TRAN. Applies separately to each category. MAXMSG may be over-ridden at run time by the NM-TRAN $WARNING record (see Users Guide VIII, $WARNING).
The following DATA statement stores constants related to day-time translation involving the year 2000:
DATA LAST20,LYWARN/50,1/
Constant LAST20 specifies the highest
2-digit year nn that is assumed to be in the 21st. century,
i.e., to represent 20nn. (If 
, the year is understood to be
. If
, the year is understood to
be 
.) With NONMEM VI, the
value of LAST20 on the distribution medium is 50 rather than
-1, as it was with NONMEM V. Hence, two-digit years nn with
nn<=50 are assumed to represent the years 2000-2050, and
two-digit years with nn>50 are assumed to represent the
years 1951-1999. If this is not correct, LAST20 can be
changed in ABLOCK and NM-TRAN recompiled, or LAST20 can be
over-ridden at run time by the LAST20 option of the NM-TRAN
$DATA record.
Constant LYWARN controls the leap year
warning message, which can appear when the year is
"00" or "0", and when LAST20 is greater
than -1 in ABLOCK. (With prior versions of NM-TRAN, the year
"00" or "0" was not a leap year. With
, the year is understood to
be 
, which is a leap year,
and the translation of dates that span February to March is
affected.) LYWARN is set to 1 on the distribution medium.
Suppose that LAST20 is changed from -1 to 50 in ABLOCK, and
LYWARN remains 1. This permits warning messages such as the
following to appear:
(DATA WARNING 3) RECORD 3, DATA ITEM 3: 01-01-00 THE YEAR IS ASSUMED TO BE 2000 (A LEAP YEAR). IF THIS IS INCORRECT, USE $DATA’S LAST20 OPTION TO OVERRIDE THE DEFAULT VALUE OF LAST20 IN NMTRAN’S ABLOCK, OR CHANGE THE CURRENT DEFAULT: 50
Change LYWARN to 0 to suppress such warnings, and recompile NM-TRAN.
BEGINX is a user-installation routine. It is called with the first executable statement of the NM-TRAN program. It allows NM-TRAN to execute statements needed with certain operating systems.
NM-TRAN reads control information from FORTRAN unit 5 and writes error messages and (unless changed as described above) warning messages to FORTRAN unit 6. Some operating systems may require that these units be explicitly opened with OPEN statements within the program. Such statements may be placed in routine BEGINX. No change to BEGINX is needed with any of the operating systems associated with the examples in this guide.
The BEGINX routine on the distribution medium contains the following code:
SUBROUTINE BEGINX
RETURN
END
NM-TRAN deletes all of its output files except FDATA when an error is detected in the NM-TRAN control stream or data file. Hence the existence of NM-TRAN output files FCON, FSTREAM, etc. can be tested to determine if NM-TRAN has terminated successfully. This is done in the UNIX and MS-DOS examples in chapter VII. An alternative way of checking for successful termination follows.
Subroutine CFILEX is the last subroutine executed by NM-TRAN. When errors are detected in the user’s input statements, it is desirable that CFILEX return an error code to the operating system. However, there is no standard way to return an error code in FORTRAN 77. CFILEX offers two possible ways of ending the program:
C CALL EXIT(N)
IF (N.GT.0) STOP 4
STOP
END
As shown, NM-TRAN executes the statement "STOP 4" if errors are detected in the user’s input statements (N≠0), and executes "STOP" if no errors were detected (N=0).
For UNIX, we suggest that you activate the "CALL EXIT(N)" statement by replacing the ’C’ in column 1 with a space. EXIT is a FORTRAN library subroutine available on many systems. The UNIX version returns the value of N to the operating system, which can be tested in a shell script.
With HP-UX FORTRAN, the statement should be
CALL EXIT(%VAL(N))
With Watcom FORTRAN 77, place an INCLUDE statement among the declarations, and change the CALL statement as follows:
INCLUDE ’FSUBLIB.FI’
...
CALL FEXIT(N)
In CMS, the library EXIT routine does not return the value of N, and the STOP statements should be used. STOP passes a "return code" (0 or 4) to the operating system, which can be tested by an EXEC, as in Chapter VII.
For other operating systems, we suggest that you consult your local systems staff.
Subroutine CTYPE contains the following statement:
IF (CHAR.GE.’a’.AND.CHAR.LE.’z’) GO TO 2
This allows lower-case characters to be used in file names. This is useful in some systems (e.g. UNIX and CTSS). If your compiler does not allow such characters, place ’C’ in column 1.
A NONMEM user with SCO UNIX 386/ix and LPI Fortran reports that this change is needed in routine READF. Locate this statement:
OPEN (14,FILE=FWORK,FORM=’UNFORMATTED’,ERR=299)
Add the option RECL=13000:
OPEN (14,FILE=FWORK,FORM=’UNFORMATTED’,ERR=299,RECL=13000)
Certain constants are used by NM-TRAN to control array sizes, and may be changed by the user. These constants are set by PARAMETER statements in the include file SIZES. Constants that are changed in SIZES take effect only after all of NM-TRAN has been recompiled.
Note that NONMEM and PREDPP and the NM-TRAN Library Routines also share the include file. Certain constants are common to more than one of these components. If you change a constant in SIZES, comments will tell you if other components of the NONMEM system should be recompiled. Appendix 2 lists all the constants and the components in which they appear.
Several of the constants in SIZES are of special interest.
Parameters LTH and LVR are used in NONMEM, PREDPP, NM-TRAN and NM-TRAN Library routines. (LVR2 is used in NONMEM and NM-TRAN). If too many theta’s, eta’s, or epsilon’s are defined in a model, NM-TRAN will produce error messages such as the following:
28 NO. OF ELEMENTS IN THETA EXCEEDS CONSTANT "LTH" IN SIZES. 454 NO. OF ELEMENTS IN OMEGA EXCEEDS CONSTANT "LVR" IN SIZES. 62 NO. OF ELEMENTS IN OMEGA AND SIGMA EXCEEDS CONSTANT "LVR" IN SIZES.
Parameter NO is used in NONMEM, NM-TRAN and the NM-TRAN Library Subroutines. It is discussed in Chapter III, Section 2.9, and in Appendix 2. NM-TRAN does not check for violations of this limit.
Parameter PC is used in NM-TRAN and the NM-TRAN Library Subroutines. It is discussed in Chapter IV, Section 1.3, and in Appendix 2.
If the value of PC is insufficient for a given model, NM-TRAN will produce this error message:
147 NUMBER OF COMPARTMENTS EXCEEDS CONSTANT "PC" IN SIZES.
The maximum value of PC is 99. If increased beyond this maximum, NM-TRAN will generate an error message similar to the following:
AN ERROR WAS FOUND IN FILE SIZES. THE CHARACTERS IN ERROR ARE: PC= 100. THE MAXIMUM VALUE OF THIS CONSTANT IS 99. 468 CHANGE THE CONSTANT IN FILE SIZES AND RECOMPILE NM-TRAN.
Parameter PG is used in PREDPP and NM-TRAN. It is discussed in Chapter IV, Section 1.3, and in Appendix 2. If it is insufficient for a given model, NM-TRAN will produce this error message:
173 NUMBER OF PK PARAMETERS EXCEEDS CONSTANT "PG" IN SIZES.
Parameter PIR is used in PREDPP and NM-TRAN. It is discussed in Chapter IV, Section 1.3, and in Appendix 2. If it is insufficient for a given model, NM-TRAN will produce an error message such as:
425 $DES: NO. OF ELEMENTS IN DA EXCEEDS CONSTANT "PIR" IN TSIZES.
NM-TRAN uses certain fixed-length arrays as internal tables during the processing of abbreviated code in $PK blocks, $ERROR blocks, etc. The arrays are large enough for all normal use of NM-TRAN. The following parameters in include file SIZES define the sizes of the arrays:
PARAMETER (DIMTMP=150) PARAMETER (DIMCNS=50) PARAMETER (DIMNEW=600) PARAMETER (DIMRV=350*LVR) PARAMETER (DIMPKS=350*LVR) PARAMETER (DIMRHS=2000*LVR) PARAMETER (DIMVRB=200) PARAMETER (DIMQ=400)
The arrays whose sizes are controlled by these parameters contribute the following number of bytes to the NM-TRAN executable (assuming that the size of an integer variable is 4 bytes and that the size of a 1 byte character variable is actually 1 byte):
If the NM-TRAN executable module is too big for a given computer, one or more of the parameters can be made smaller.
If the amount or complexity of the abbreviated code is large, one of several error messages related to the above parameter values may be produced. In many cases it is possible to avoid the error message by modifying the NM-TRAN control stream. This is the best course of action. If it is not possible, make the appropriate modifications to SIZES, recompile the indicated routines, and rebuild the NM-TRAN executable, as detailed next.
NOTE THAT SOME OF THESE CHANGES ALSO REQUIRE CHANGES TO NONMEM, OR TO CERTAIN OF THE NM-TRAN LIBRARY SUBROUTINES.
152 INTERNAL TABLE SIZE EXCEEDED; DIMVRB IS TOO SMALL.
This message indicates that too many lines of verbatim code are present. The user should first try to decrease the number of lines of verbatim code. If the message cannot be avoided, increase the value of DIMVRB in main program NM-TRAN (e.g., change DIMVRB=200 to DIMVRB=400) and recompile main program NMTRAN (or recompile all of NM-TRAN if it has not been separated into individual files).
No other changes are necessary.
198 INTERNAL TABLE SIZE EXCEEDED; DIMTMP IS TOO SMALL.
This message indicates that too many variables are present. New variables are defined by the user and by NM-TRAN itself. The user should first try to decrease the number of variable names in the abbreviated code. If the message cannot be avoided, increase the value of DIMTMP in SIZES (e.g., change DIMTMP=150 to DIMTMP=300) and recompile all of NM-TRAN.
Certain NM-TRAN subroutines will also have to be changed: see Chapter VI, Section 2.1.2.
199 INTERNAL TABLE SIZE EXCEEDED; DIMCNS IS TOO SMALL.
This message indicates that too many constants are present. New constants are defined by the user and by NM-TRAN itself. The user should first try to decrease the number of constants in the abbreviated code. If the message cannot be avoided, increase the value of DIMCNS in SIZES (e.g., change DIMCNS=50 to DIMCNS=100) and recompile main program NMTRAN (or recompile all of NM-TRAN if it has not been separated into individual files).
Certain NM-TRAN subroutines will also have to be changed: see Chapter VI, Section 2.1.2.
204 INTERNAL TABLE SIZE EXCEEDED; DIMPKS IS TOO SMALL.
This message indicates that too many lines of code are present, including both abbreviated code and additional lines of code inserted by NM-TRAN. This message is accompanied by one of the following, depending if $PRED or other blocks of abbreviated code are present:
BECAUSE SECOND DERIVATIVES ARE NOT NEEDED UNLESS LAPLACIAN OPTION IS USED, TRY INCLUDING $ABBREVIATED DERIV2=NO (PRIOR TO $PRED). ALSO, SEE GUIDE III. BECAUSE SECOND DERIVATIVES ARE NOT NEEDED UNLESS LAPLACIAN OPTION IS USED, TRY INCLUDING $ABBREVIATED DERIV2=NO (PRIOR TO $PK). ALSO, SEE GUIDE III.
NM-TRAN inserts many lines of code in order to compute derivatives; second derivatives are especially costly in this respect. However, whereas first derivatives are needed for virtually all NONMEM tasks using population data, second derivatives are needed only with the Laplacian method, i.e., if the control stream includes $ESTIMATION METHOD=1 LAPLACIAN. If the Laplacian method is not requested, NM-TRAN can be instructed not to generate lines of code to compute these derivatives by inserting the following control record in the NM-TRAN control stream before the first block of abbreviated code:
$ABBREVIATED DERIV2=NO
(If this is done and subroutines are generated, the resulting executable must not be re-used with the Laplacian method.) If the message cannot be avoided, increase the value of DIMPKS in SIZES (e.g., change DIMPKS=1500 to DIMPKS=2500) and recompile main program NMTRAN (or recompile all of NM-TRAN if it has not been separated into individual files).
No other changes are necessary.
205 INTERNAL TABLE SIZE EXCEEDED; DIMRHS IS TOO SMALL.
This message indicates that there are too many right-hand-side symbols. It is very similar to 204 and arises from similar causes. It is accompanied by the same messages as 204; please read the discussion for message 204. If the message cannot be avoided, increase the value of DIMRHS in SIZES (e.g., change DIMRHS=8000 to DIMRHS=12000) and recompile main program NMTRAN (or recompile all of NM-TRAN if it has not been separated into individual files).
No other changes are necessary.
212 INTERNAL TABLE SIZE EXCEEDED; DIMRV IS TOO SMALL.
This message indicates that NM-TRAN has created too many variables associated with partial derivatives. It is very similar to 204 and arises from similar causes. It is accompanied by the same messages as 204; please read the discussion for message 204. If the message cannot be avoided, increase the value of DIMRV in SIZES (e.g., change DIMRV=1500 to DIMRV=3000) and recompile main program NMTRAN (or recompile all of NM-TRAN if it has not been separated into individual files).
Certain NM-TRAN subroutines will also have to be changed: see Chapter VI, Section 2.1.2.
226 INTERNAL TABLE SIZE EXCEEDED; DIMNEW IS TOO SMALL.
This message indicates that NM-TRAN has created too many intermediate variables. It is very similar to 204 and arises from similar causes. It is accompanied by the same messages as 204; please read the discussion for message 204. If the message cannot be avoided, increase the value of DIMNEW in SIZES (e.g., change DIMNEW=300 to DIMNEW=600) and recompile main program NMTRAN (or recompile all of NM-TRAN if it has not been separated into individual files).
Certain NM-TRAN subroutines will also have to be changed: see Chapter VI, Section 2.1.2.
294 INTERNAL TABLE SIZE EXCEEDED; DIMRV IS TOO SMALL FOR DES, AES.
This message is very similar to 212. Please read the discussion for message 212.
393 INTERNAL TABLE SIZE EXCEEDED; DIMQ IS TOO SMALL.
This message indicates that NM-TRAN has created too many variables associated with logical conditions. Reduce the number of IF statements in abbreviated code that assign values to random variables. If the message cannot be avoided, increase the value of DIMQ in SIZES (e.g., change DIMQ=400 to DIMQ=800) and recompile main program NMTRAN (or recompile all of NM-TRAN if it has not been separated into individual files).
Certain NM-TRAN subroutines will also have to be changed: see Chapter VI, Section 2.1.2.
Parameter LNP4 is used by NONMEM and NM-TRAN. It is discussed in Chapter III, Section 2.9, and in Appendix 2. The error message from NM-TRAN is:
288 SIZE OF NMPRD4 EXCEEDED; LNP4 IS TOO SMALL IN NMTRAN AND NONMEM
This message indicates that the number of PRED-defined variables, created by the user and by NM-TRAN, exceeds the number that can be stored in COMMON NMPRD4. This message is accompanied by one of the following, depending if $PRED or other blocks of abbreviated code are present:
BECAUSE ONLY SECOND DERIVATIVES TO BE DISPLAYED NEED BE STORED IN COMMON NMPRD4 TRY INCLUDING $ABBREVIATED DERIV2=NOCOMMON (PRIOR TO $PRED) OR, IF NECESSARY, COMRES=-1. ALSO, SEE GUIDE III. TRY INCLUDING $ABBREVIATED DERIV2=NOCOMMON (PRIOR TO $PK) OR, IF NECESSARY, COMRES=-1. ALSO, SEE GUIDE III.
NMPRD4 is the name of a FORTRAN COMMON (global storage area) shared between NONMEM and PRED. With a PRED other than PREDPP, it serves only one essential purpose: it communicates the values of PRED-defined variables to NONMEM so that these variables can be displayed in tables or scatterplots. With PREDPP and $PK and $ERROR abbreviated code, it serves an additional purpose: it is also used to communicate to ERROR the values of variables computed in PK. These variables include those defining derivatives.
NM-TRAN creates many variables in order to compute derivatives; second derivatives are especially costly in this respect, and are most likely the cause of this error message. If none of the NM-TRAN-generated variables defining second derivatives are to be displayed, and (in the case of PREDPP) no such variables need be communicated between PK and ERROR via COMMON NMPRD4, then these variables need not be stored in the common. (Variables which are computed in PK and are used in ERROR can always be recomputed in ERROR.) NM-TRAN can be instructed not to place variables defining second derivatives in the common by inserting the following control record in the NM-TRAN control stream before the first block of abbreviated code:
$ABBREVIATED DERIV2=NOCOMMON
Note that the resulting executable may still be used with the Laplacian method, because second derivatives are still computed.
If the error message persists, the user should exclude from the common all variables from one or all blocks of abbreviated code. Again, this affects only the ability to display variables and to communicate between PK and ERROR.
To eliminate use of COMMON NMPRD4 in a single block of abbreviated code, the pseudo-statement ’COMRES=-1’ may be placed in the NM-TRAN control stream immediately after the start of the block of abbreviated code, e.g.:
$PK COMRES=-1
To eliminate use of COMMON NMPRD4 in all blocks of abbreviated code, the following control record should be placed in the NM-TRAN control stream before the first block of abbreviated code:
$ABBREVIATED COMRES=-1
If the message cannot be avoided, increase the value of LNP4 in SIZES (e.g., change LNP4=1000 to LNP4=2000) and recompile main program NMTRAN (or recompile all of NM-TRAN if it has not been separated into individual files). See Chapter III, Section 3, and Appendices 4 and 5.
Certain NM-TRAN subroutines will also have to be changed: see Chapter VI, Section 2.1.1.
NONMEM must also be changed; see Chapter III, Section 2.8.
When bugs are found in NM-TRAN, the fixes are described in emails and technical newsletters. Please check any emails or newsletters that may have been sent with the NONMEM distribution medium or that are received afterwards. You will have to modify the source code and recompile portions of NM-TRAN.
See also Chapter 1, Section 7, for internet sites of interest.
You should now compile NM-TRAN using a FORTRAN 77 compiler and save the resulting object code for later use. If NM-TRAN is one large file, it can be compiled in this form. If it has been separated into two or more files, each must be compiled separately. No warning or error messages are expected. Optimized compiles are not needed. If error messages concerning the include file SIZES occur, it may be necessary to rename the include file. See Chapter III, Section 3.4. If error messages are produced, please phone the NONMEM consultant before you attempt to fix the source code yourself. (In UNIX and MS-DOS, warning and error messages will be found in file emsgs.txt.) Note that NM-TRAN requires no additional user-written subroutines and should be ready to run.
|
UNIX: |
f77 -o nmtran *.for >& emsgs.txt
|
MS-DOS: |
Using PowerStation Fortran:
fl32 /Fenmtran *.for > emsgs.txt
Using DIGITAL Visual Fortran:
df /Fenmtran *.for > emsgs.txt
A user with Watcom FORTRAN 77 suggests these instructions:
wfl386 /c *.for wfl386 /fe=nmtran *.obj
|
CMS: |
Make a file called ADDTRAN EXEC A containing the statement:
TXTLIB ADD TRAN &2
Input the following commands:
TRAN EXEC COMPILE TXTLIB GEN TRAN NMTRAN TRAN EXEC ADDTRAN
You may now erase NM-TRAN TEXT files and recreate ABLOCK TEXT A:
TRAN EXEC ERASE2 FORTVS ABLOCK
This section describes all external files used by NM-TRAN. Figures 7.1 and 7.2 of Chapter VII are flowcharts which show how these files are used during an NM-TRAN/NONMEM run; it may help to look at these figures now.
The following table lists the files used by NM-TRAN with their default names and unit numbers. (ABLOCK is discussed in Section 2.1; n/a means "not applicable".)
† Optional. ‡ Only if WU is given a value other than 6.
NM-TRAN control file
|
The NM-TRAN control file is read from FORTRAN unit 5. The record length is 80 bytes. |
NM-TRAN data file
|
The NM-TRAN input data file is opened (with STATUS=’OLD’) and read from the file named on the NM-TRAN $DATA record. The maximum record length is 300 bytes. If a format specification is included on the $DATA record, the file is read according to the given format. If no format specification is given but the LRECL option is used, the number of characters read is the number given by LRECL. If neither is present, NM-TRAN attempts to read 300 bytes. If the records are shorter than 300 bytes and this causes a fatal operating system error (as with CMS; see Section 5.3), the LRECL option should be used. With UNICOS on the CRAY, we have found it necessary to
set the lengths of certain FORTRAN I/O buffers to larger
values than the default in order to avoid fatal errors in
NM-TRAN that occur when a format specification is included
on the $DATA record. The cf77 command that creates the
executable NM-TRAN executable should include an option such
as: -Wl"-i seg.directive" SET=$RBUFLN:13000 COMMONS=$RFDCOM:13009 SET=$WBUFLN:13000 COMMONS=$WFDCOM:13009 (A different name can be used for the file.) |
User-supplied subroutines
|
Files containing user-supplied subroutines that are named on the NM-TRAN $SUBROUTINES record are opened and read, unless NM-TRAN was modified so that user-supplied subroutines are not copied to FSUBS, as discussed in Section 2.1.2. The maximum record length for these FORTRAN source files is 80 bytes. |
NM-TRAN include files
|
NM-TRAN implements an include feature much like that of the FORTRAN compiler. Lines starting with the characters "INCLUDE" may be placed anywhere in the control stream. E.g., INCLUDE ’includename’ The named file is opened and its contents are read to end of file and inserted into the NM-TRAN control stream, exactly as if it had been typed into in the NM-TRAN control stream. |
FWORK
|
NM-TRAN uses a work file called FWORK. It is an unformatted file with record length 13,000 bytes. With CMS, no FILEDEF statement is normally needed for this file. A file named FILE FWORK A is automatically opened and deleted at the end of the NM-TRAN run. However, with IBM VS FORTRAN Level 2.5.0, a system warning message AFB201I may appear when the NM-TRAN data file is large because this release of FORTRAN defines the default maximum unformatted record length to be 796. The default can be changed; e.g., see IBM Manual SC26-4339-4, VS FORTRAN Version 2 Installation and Customization for CMS Release 5, page 36. Alternately, you can include this FILEDEF statement each time NM-TRAN is run: FILEDEF FWORK DISK FWORK DATA A ( RECFM U LRECL 13000 See Section 1.5 above for a change to the OPEN statement that has been recommended for LPI Fortran. |
All output files are sequential formatted files. The record length is always 80, except possibly for FDATA.
Error Messages
|
NM-TRAN may encounter errors in the NM-TRAN data or control file. If so, it writes error messages to FORTRAN unit 6 and aborts processing. |
With an interactive operating system, unit 6 should always be directed to the terminal so that the user can see the messages and correct errors immediately. (NM-TRAN takes only a short time to run compared with NONMEM).
Warning messages are also written to unit 6, although this can be changed (see Section 1.1.4 above). The user should carefully review the warning messages. Messages of no interest may be suppressed temporarily (using the NM-TRAN $WARNING record) or permanently (see Section 1.1.4).
The following files are produced ONLY if no error messages are written. If NM-TRAN terminates because of error messages, they are removed if they existed previously. (FDATA is an exception. If the run is terminated due to errors in the NM-TRAN data file, it may be helpful to be able to see the output of the data preprocessor prior to the termination.)
|
FCON |
FCON is the NONMEM control file. |
FDATA
|
If the data preprocessor modifies the NM-TRAN data file, the NONMEM data file is written to file FDATA. If a format specification is included on the $DATA record and the record length of the NM-TRAN data file is greater than 80 bytes, then the record length of FDATA is the same as that of the NM-TRAN data file. Otherwise, by default the record length of FDATA is no greater than 80 bytes, and no greater than 300 bytes if the option WIDE appears on the $DATA record. (Thus, for CMS, LRECL must be specified on the FILEDEF statement for FDATA only if it had to be specified on the FILEDEF statement for the NM-TRAN data file itself.) |
FSTREAM
|
FSTREAM is the NONMEM file control stream. It contains the names of certain files to be opened by NONMEM. These are: |
|
The name of the NONMEM data file (either the NM-TRAN data file name as specified on the NM-TRAN $DATA record, or the name FDATA if the NM-TRAN data file was modified.) File names specified via $MSFI records. File names specified via the MSFO option of $ESTIMATION records. File names specified via the FILE option of $TABLE records. |
FREPORT
|
FREPORT is a report describing exactly which subroutines should be included in the NONMEM executable. The use of FREPORT is discussed in Chapter VII. |
|
FLIB |
FLIB is written if the NM-TRAN control file includes abbreviated code and the $SUBROUTINES record specifies the LIBRARY option. This file contains tables of instructions for the general-purpose NM-TRAN subroutines. Otherwise, the file is not created and is removed if it existed previously. |
FSUBS
|
FSUBS contains FORTRAN subroutines to be compiled and linked with other NONMEM subroutines. It contains: |
|
1) |
Generated FORTRAN subroutines if the NM-TRAN control file includes abbreviated code, and if the $SUBROUTINES record does not specify the LIBRARY option. |
|
2) |
FORTRAN source code for any user-supplied subroutines named on the $SUBROUTINES record (unless NM-TRAN is modified as in Section 2.1.2). Source files containing such code are copied into FSUBS but are not checked in any way. They may, for example, be empty files. |
|
If there is no code to be compiled, FSUBS is not created, and is removed if it existed previously. |
The simple NM-TRAN test case does not involve running NONMEM-PREDPP, but simply tests NM-TRAN’s ability to read input files and construct files for a subsequent NONMEM-PREDPP run. (Chapter VII discusses how to combine these steps into one.) Use the example in Appendix IX of NONMEM Users Guide, Part IV.
You may read the NM-TRAN control stream from file "CONTROL3" and the data file from file "DATA3" of the distribution medium. Alternately, using your system’s editor, type the NM-TRAN control stream and data set into disk files. (You do not have to type the contents of the files exactly as shown as you did with the NONMEM and PREDPP tests. Allow at least one space between words in the control file and at least one space between values in the data file. Start new lines where shown. Blank lines and comment lines (i.e., lines starting with ’;’) are optional.)
In the NM-TRAN $DATA record of the example, DATA3 is the file name used in a FORTRAN OPEN. This file name must be connected to the actual disk file in some way.
In UNIX and MS-DOS, give the actual data file on disk the name DATA3.
In CMS, connect the disk data file using a FILEDEF statement. (Note that VS FORTRAN restricts you to a 1-7 character file name on the NM-TRAN $DATA record.) Suppose the data file on disk has the name DATA3 DATA A:
FILEDEF DATA3 DISK DATA3 DATA A
In VAX VMS, it may be helpful to specify data file names
with the extension ".DAT", as in this
example:
$DATA MY_ROOT:[ppm.flx]FLXDATA.DAT
With some operating systems (including CMS) an operating system I/O error might occur when NM-TRAN attempts to read the data file, for the following reason. When NM-TRAN does not know the input record length, it attempts to read its maximum size record (300 bytes). If the actual record length is smaller, the operating system generates an error message. If this happens, use the LRECL option on the $DATA record to specify the logical record length of the data file. For example, if the data file was constructed using CMS’s XEDIT, the logical record length is 80 by default and the $DATA record should be:
$DATA filename LRECL=80
(Larger values than 80 may be used with CMS, if appropriate.)
Now run NM-TRAN with the test control file used as input on FORTRAN unit 5 and directing the output on FORTRAN unit 6 to the terminal, if necessary. In the following examples, the test control file is named control3 for UNIX and MS-DOS and CONTROL3 DATA A for CMS.
|
UNIX: |
nmtran < control3
|
MS-DOS: |
nmtran < control3
|
CMS: |
FILEDEF 5 DISK CONTROL3 DATA A FILEDEF 6 TERMINAL ( LRECL 133 RECFM F FILEDEF DATA3 DISK DATA3 DATA A FILEDEF FDATA DISK FDATA DATA A FILEDEF FSTREAM DISK FSTREAM DATA A FILEDEF FLIB DISK FLIB DATA A FILEDEF FCON DISK FCON DATA A FILEDEF FSUBS DISK FSUBS FORTRAN A FILEDEF FREPORT DISK FREPORT DATA A GLOBAL TXTLIB VSF2LINK VSF2FORT CMSLIB TRAN LOAD NMTRAN ABLOCK ( START
The following output can be expected to appear at the terminal:
WARNINGS AND ERRORS (IF ANY) FOR PROBLEM 1 (WARNING 1) NM-TRAN INFERS THAT THE DATA ARE SINGLE-SUBJECT.
This is an informational message from NM-TRAN. With every run, you will see it or its companion message:
(WARNING 2) NM-TRAN INFERS THAT THE DATA ARE POPULATION.
These messages warn you of an important inference that NM-TRAN has made based on the control stream. These and other warning messages may be suppressed with the NM-TRAN $WARNING record. The presence of a warning message is not a fatal error and NM-TRAN permits the NONMEM run to take place. NM-TRAN can also be modified to write warning messages to a disk file.
Ideally, warning messages (other than the two mentioned above) and error messages will not appear at the terminal. If an error message appears, correct the error and try again. If error messages persist, please call the NONMEM consultant before you attempt to change NM-TRAN source code. Be prepared to state the error number which precedes the text of the error message.
If no error messages appear at the terminal, several new files will have been created. Examine the files and make sure that each is the same as the version printed in Appendix IX of NONMEM Users Guide, Part IV.
In VAX VMS, the first character of each line of these files may not appear when the file is displayed, even though the first character is physically present in the file and will be read by NONMEM. If this is a cause of concern, the OPEN statements in NM-TRAN subroutine OFILEX can be modified to include a CARRIAGECONTROL option to inform the operating system that the first character is not used for FORTRAN carriage control. E.g.,
OPEN (15,FILE=FCON,ERR=10,CARRIAGECONTROL=’LIST’)
If the output files are correct, you have successfully installed NM-TRAN.
However, this does not constitute an adequate test that NONMEM VI itself has been installed correctly. To test NONMEM VI, we recommend that CONTROL5 and data set THEOPP be used next. These files can be read from the distribution medium. References to CONTROL3 and DATA3 should be changed to CONTROL5 and THEOPP in sections 5.1, 5.2, and 5.4 above. The warning message will be
(WARNING 2) NM-TRAN INFERS THAT THE DATA ARE POPULATION.
To check that the output file is correct, compare it
with the file at
ftp://ftp.globomaxnm.com/Public/nonmem/output/control5.out.
If you intend to use NM-TRAN library subroutines, proceed to Chapter VI. Otherwise, proceed to Chapter VII.
TOP
TABLE OF CONTENTS
NEXT CHAPTER ...