14

SUN/114.4

Starlink Project
Starlink User Note 114.4

Malcolm J. Currie
Alan J. Chipperfield

2019 November 30

PAR
Interface to the ADAM Parameter System

Version 2.4

Programmer’s Manual

Abstract

PAR is a library of Fortran subroutines that provides convenient mechanisms for applications to exchange information with the outside world, through input-output channels called parameters. Parameters enable a user to control an application’s behaviour. PAR supports numeric, character, and logical parameters, and is currently implemented only on top of the ADAM parameter system.

The PAR library permits parameter values to be obtained, without or with a variety of constraints. Results may be put into parameters to be passed onto other applications. Other facilities include setting a prompt string, and suggested defaults.

This document also introduces a preliminary C interface for the PAR library – this may be subject to change in the light of experience.

Contents

1 Introduction
2 What is a Parameter?
3 Parameter States
4 Error Handling
5 Basic Routines
5.1 Getting a Parameter’s Value
5.2 Getting an Array of Values
5.3 Putting a Parameter’s Value
5.4 Cancelling a Parameter
5.5 Setting the Dynamic Prompt
5.6 Setting the Dynamic Default
5.7 Setting Lower and Upper Limits
5.8 Cancelling Dynamic Values
5.8.1 Range
5.8.2 Dynamic Defaults
5.9 Inquiring the State of a Parameter
6 Abort and Null
6.1 Abort
6.2 Null
7 Extended Routines
7.1 Scalar Values between Limits
7.2 Arrays of Values between Limits
7.3 Parity Constraint
7.4 Menu Constraint
7.5 Combined Constraints
7.6 Logical Value
8 Other Types of Parameters
9 Compilation and Linking
9.1 UNIX
9.2 VMS
10 Acknowledgements
A Alphabetical List of Routines
B Classified List of Routines
B.1 Getting Values from a Parameter without Constraints
B.2 Getting Parameter Values from a Menu
B.3 Getting Values within Ranges
B.4 Putting Values into Parameters
B.5 Miscellaneous
B.6 Inquiry Routines
C Error Codes
D Correspondence between PAR and SUBPAR States
E The C Interface
F The C Interface Function Prototypes
G Reference Manual

PAR_CANCL – Cancels a parameter

PAR_CHOIC – Obtains from a parameter a character value selected from a menu of options

PAR_CHOIV – Obtains from a parameter a list of character values selected from a menu of options

PAR_DEF0x – Sets a scalar dynamic default parameter value

PAR_DEF1x – Sets a vector of values as the dynamic default for a parameter

PAR_DEFNx – Sets an array of values as the dynamic default for a parameter

PAR_EXACx – Obtains an exact number of values from a parameter

PAR_GDR0x – Obtains a scalar value within a given range from a parameter

PAR_GDR1x – Obtains an exact number of values within a given range from a parameter

PAR_GDRVx – Obtains a vector of values within a given range from a parameter

PAR_GET0x – Obtains a scalar value from a parameter

PAR_GET1x – Obtains a vector of values from a parameter

PAR_GETNx – Obtains an array parameter value

PAR_GETVx – Obtains a vector of values from a parameter regardless of the its shape

PAR_GEVEN – Obtains an even integer value from a parameter

PAR_GODD – Obtains an odd integer value from a parameter

PAR_GRM1x – Obtains from a parameter an exact number of values each within a given range

PAR_GRMVx – Obtains from a parameter a vector of values each within a given range

PAR_GTD0L – Obtains a logical value from a parameter with a dynamic default

PAR_MAXx – Sets a maximum value for a parameter

PAR_MINx – Sets a minimum value for a parameter

PAR_MIX0x – Obtains from a parameter a character value from either a menu of options or within a numeric range

PAR_MIXVx – Obtains from a parameter character values from either a menu of options or within a numeric range

PAR_PROMT – Sets a new prompt string for a parameter

PAR_PUT0x – Puts a scalar value into a parameter

PAR_PUT1x – Puts a vector of values into a parameter

PAR_PUTNx – Puts an array of values into a parameter

PAR_PUTVx – Puts an array of values into a parameter as if the parameter were a vector

PAR_STATE – Inquires the state of a parameter

PAR_UNSET – Cancels various parameter control values.