int result; int waitstat; int stat = PmcaAsyncGetGain(&result); // stat receives request id

Transcription

1 PMCA COM API Programmer's Guide PMCA COM is an Application Programming Interface Library for the Amptek Pocket Multichannel Analyzers MCA8000 and MCA8000A. PMCA COM runs on personal computers under any of Win32 operating systems (Windows 95/98/ME/2000/NT, or Windows CE with modifications). Application programs invoke PMCA COM functions to establish communication with PMCA, control its operation, and retrieve data. PMCA COM is distributed in two forms, as an object link library (.LIB) or Dynamic Link Library (.DLL). The application executable programs (.EXE) are created by linking the application code with one of these libraries statically or dynamically (see Microsoft documentation about program linking). The applications can be developed in C, Visual Basic or any other language. PMCA COM API functions have the prefix Pmca and usually include action verbs and the names of items to which the actions are related (e.g. PmcaGetData). All functions return an integer type value representing either the requested parameter or error code. All error codes are negative. The error can be a PMCA COM error or a system error. PMCA COM error codes have bit 28 set in accordance with the Win32 convention (see Microsoft documentation). The C language representation of PMCA COM functions is defined in the PmcaCom.h header file. The PMCA COM errors are defined in PmcaErr.h. These files are provided with the PMCA COM libraries. There are only a few functions that do not require communication between the PMCA and the host. The majority of functions initiate some kind of interaction with PMCA. These functions may take a long time to execute. PMCA COM provides two versions of functions that require interaction with PMCA: synchronous and asynchronous. Synchronous functions do not return to the calling procedure until the operation is complete. Asynchronous functions return to the caller immediately and execute the operation in background. This allows for better response of applications to other tasks, e.g. user interface tasks. Asynchronous functions have an additional parameter, a pointer to the field that will receive the result of the operation on the function completion. All other parameters are identical to those in synchronous functions. The asynchronous function returns the identifier of the request. The application can poll the result filed to find out about the operation status or it can later suspend itself and wait until the operation completion by calling the PmcaWait function. The following lines illustrate the use of asynchronous functions: int result; int waitstat; int stat = PmcaAsyncGetGain(&result); // stat receives request id if (stat > 0) {.. Do something. waitstat = PmcaWait(stat); if (waitstat >= 0) // gain value is stored in result } sales@amptek.com Page 1 of 15

2 Before any interaction with the PMCA (excluding power up) can take place, the application program must call the PmcaConnect function. The PmcaPowerUp function must be called before PmcaConnect if the PMCA is not powered manually. When the PMCA is connected, PMCA COM creates two threads of execution, EXEC and MONITOR. The EXEC thread executes requests for interaction with PMCA. These requests are generated by PMCA COM API functions and are placed in the EXEC queue. The EXEC thread retrieves requests from its queue and executes them one at a time. Usually the EXEC thread runs on a relatively low priority to allow other processes and threads to perform their important tasks. The application can change the EXEC thread priority by calling the PmcaSetPriority function. The priority has seven levels from 0 to 6, with level 0 corresponding to Win32 priority THREAD_PRIORITY_IDLE and level 6 - THREAD_PRIORITY_TIME_CRITICAL (see Microsoft documentation for details). The MONITOR thread runs with a high priority. Its function is to prevent the EXEC thread from CPU time starvation. Most of the time the MONITOR thread is inactive. It periodically wakes up and checks whether the EXEC task requires more CPU time to perform its operations. If so it temporarily boosts the EXEC thread priority to THREAD_PRIORITY_HIGHEST. The EXEC and MONITOR threads are terminated when PmcaTerminateCom is called. The application should call PmcaTerminateCom before exiting the program. PMCA COM data types PMCA COM data types define special values and layout of records used in exchange of data between the host computer and the PMCA. These data types are declared in PmcaCom.h file. PmcaDeviceType is an enumerator that defines types of PMCA devices. An object of this type can have one of the following values: PMCA_AUTO_DETECT PMCA_8000 PMCA_8000A PMCA_AUTO_DETECT value is used only in PmcaConnect call to request automatic identification of the attached device. PmcaBatteryType identifies type of main battery. Valid values are PMCA_LI - alkaline PMCA_NICAD - nickel-cadmium PmcaFlagsType contains some information about the state of PMCA. The following is its C language declaration: typedef union { struct { unsigned char gain:3; // Gain index from 0 to 6 (gain 16,384 to 256) sales@amptek.com Page 2 of 15

3 unsigned char live:1; // Live timing when set, otherwise real unsigned char acquire:1; // PMCA is acquiring data (when set) unsigned char secure:1; // PMCA is protected (when set) unsigned char batterytype:1; unsigned char batterycondition:1; // Battery is bad (when set) } bits; unsigned char byte; } PmcaFlagsType; PmcaFlagsType is a part of PmcaControlType: typedef struct { PmcaFlagsType flags; unsigned short threshold:15; unsigned short absolutepeak:1; } PmcaControlType; In turn, PmcaControlType is a part of PmcaStatusType. PMCA sends the status information to the host in this format: typedef struct { unsigned char checksum; PmcaControlType control; unsigned long livetime75:8; unsigned long livetime:24; unsigned long realtime75:8; unsigned long realtime:24; unsigned long battery:8; unsigned long presettime:24; union { unsigned long checksum; struct { unsigned short group:10; unsigned short spare:6; unsigned short serialnumber; } gsn; } u; } PmcaStatusType; sales@amptek.com Page 3 of 15

4 Description of PMCA COM API functions Get Device Type PmcaDeviceType PmcaGetDeviceType(void); Return: type of attached device. Comment: this is the only function that does not return integer; the function always succeeds. Set Priority int PmcaSetPriority(int priority); Sets priority of the EXEC thread. Input: priority Ranges from 0 to 6 (corresponds to Win32 priorities THREAD_PRIOTITY_IDLE to THREAD_PRIORITY_TIME_CRITICAL) Return: error code (always PMCA_ERROR_SUCCESS) Cancel (request) int PmcaCancel(int id); Cancels a request that has been previously initiated by an asynchronous procedure call. Input: id - request identifier that was returned when an asynchronous function was called errors: PMCA_ERROR_REQUEST_NOT_FOUND - either the request has been already completed or the identifier is invalid Wait (for request completion) int PmcaWait(int id); Suspends the application thread until the request is completed. sales@amptek.com Page 4 of 15

5 Input: id - request identifier that was returned when an asynchronous function was called return: result of the operation or error code errors: PMCA_ERROR_REQUEST_NOT_FOUND - either the request has been already completed or the identifier is invalid Disconnect int PmcaDisconnect(void); Disconnects PMCA from the communication port and releases it Terminate int PmcaTerminateCom(void); Terminates communication threads Power Up int PmcaPowerUp(int port); int PmcaAsyncPowerUp(int *result, int port); Turns on PMCA power. Input: port - communication port number PMCA is connected to. Connect int PmcaConnect(int port, int baudrate, PmcaDeviceType device); sales@amptek.com Page 5 of 15

6 int PmcaAsyncConnect(int * result, int port, int baudrate, PmcaDeviceType device); Establishes communication with PMCA Inputs: port - communication port number baudrate - requested baudrate (must between 1200 and ) device - PMCA device type; if device is PMCA_AUTO_DETECT the system attempts to identify the device Get serial number int PmcaGetSerialNumber(void); int PmcaAsyncGetSerialNumber(int *result); Retrieves the serial number of the attached device return: serial number or error code Get battery type int PmcaGetBatteryType(void); int PmcaAsyncGetBatteryType(int *result); Checks the main battery type in PMCA return: battery type or error code Get battery condition int PmcaGetBatteryCondition(void); int PmcaAsyncGetBatteryCondition(int *result); Checks the backup battery condition in PMCA return: battery condition or error code sales@amptek.com Page 6 of 15

7 Get battery capacity MCA8000A Programmer s Guide (API) Amptek Inc. int PmcaGetBatteryCapacity(void); int PmcaAsyncGetBatteryCapacity(int *result); Checks the remaining capacity of the main battery in PMCA return: percentage of the remaining battery capacity or error code Get group int PmcaGetGroup(void); int PmcaAsyncGetGroup(int *result); Retrieves the current group return: current group or error code Get gain int PmcaGetGain(void); int PmcaAsyncGetGroup(int *result); Returns the current gain return: current gain or error code Get real time int PmcaGetRealTime(void); int PmcaAsyncGetRealTime(int *result); Retrieves the value of the real time counter from PMCA (in ms) return: real timer value or error code sales@amptek.com Page 7 of 15

8 Get live time int PmcaGetLiveTime(void); int PmcaAsyncGetLiveTime(int *result); Retrieves the value of the live timer from PMCA (in ms) return: live timer value or error code Get flags int PmcaGetFlags(PmcaFlagsType *flags); int PmcaAsyncGetFlags(int *result, PmcaFlagsType *flags); Retrieves PMCA flags structure from PMCA output: flags Get status int PmcaGetStatus(PmcaStatusType *status); int PmcaAsyncGetStatus(int *result, PmcaStatusType *status); Retrieves PMCA status structure from PMCA output: status Get data int PmcaGetData(unsigned long *buffer, int channel, int count); int PmcaAsyncGetData(int *result, unsigned long *buffer, int channel, int count); Retrieves data from specified memory group. input: channel starting channel Page 8 of 15

9 count number of channels to retrieve data from output: buffer NOTE: It is possible to retrieve data from higher groups than the present group. Set the starting channel parameter to the last channel of the current group. Then set the count parameter for the desired number of channels. This will download the last channel of the current group (which can be ignored) and the specified channles in the next group or groups. For example, if the MCA8000A is presently in 1024 channel mode and in group 0 and the PmcaGetData(buffer, 1023, 2049) command is sent, the MCA will download the last channel of group 0, all of group 1, and all of group 2. There is no way to download data from previous memory groups (e.g. being in the group 1 and downloading data from group 0). Get date and time int PmcaGetDateAndTime(char *datetime); int PmcaAsyncGetDateAndTime(int * result, char *datetime); Retrieves time stamp and stores it in datetime buffer as MM/DD/YYYY HH:MM:SS output: datetime - character buffer at least 20 characters long Set absolute peak mode int PmcaSetAbsolutePeakMode(void); int PmcaAsyncAbsolutePeakMode(int *result); Defines the data acquisition mode as absolute peak detection Note: The MCA8000A defaults to first peak mode on power up. If absolute peak mode is the desired mode of operation, the set absolute peak mode command must be sent every time the MCA8000A is powered on. Set first peak mode int PmcaSetFirstPeakMode(void); sales@amptek.com Page 9 of 15

10 int PmcaAsyncFirstPeakMode(int *result); Defines the data acquisition mode as first peak detection Note: First peak mode is the default state of the MCA8000A when it is powered on. The first peak mode command only needs to be sent if the MCA8000A has been switched to abolute peak mode since the last time it was powered on. Select real timer int PmcaSelectRealTimer(void); int PmcaAsyncSelectRealTimer(int *result); Selects real timer for data acquisition Select live timer int PmcaSelectLiveTimer(void); int PmcaAsyncSelectLiveTimer(int *result); Selects live timer for data acquisition Clear data int PmcaClearData(void); int PmcaAsyncClearData(int *result); Clears data in the current group Page 10 of 15

11 Clear time int PmcaClearTime(void); int PmcaAsyncClearTime(int *result); Resets acquisition time in the current group Clear data and time int PmcaClearDataAndTime(void); int PmcaAsyncClearDataAndTime(int *result); Clears data in the current group and resets acquisition time Start acquisition int PmcaStartAcquisition(int setstamp); int PmcaAsyncStartAcquisition(int *result, int setstamp); Starts acquisition and if setstamp parameter is not zero sets start time stamp to current time input: setstamp - if not zero start stamp will be set to current time Stop acquisition int PmcaStopAcquisition(void); int PmcaAsyncStopAcquisition(int *result); Stops acquisition sales@amptek.com Page 11 of 15

12 Note: The MCA8000A can not be stopped sooner than one second after the start command has been sent. If the stop command is sent sooner than one second after the start command the MCA8000A will stop at one second. Set group int PmcaSetGroup(int group); int PmcaAsyncSetGroup(int *result, int group); Selects the specified group as the current group input: group Set gain (ADC resolution) int PmcaSetGain(int gain); int PmcaAsyncSetGain(int *result, int gain); Defines gain (ADC). Gain should be a power of 2. If it is not, then it is rounded up to the nearest valid value. For example, 250 is rounded to 256 and 16,000 to 16,384. input: gain - must be between 129 and 16,384 Set time int PmcaSetTime(char *time); int PmcaAsyncSetTime(int *result, char *time); Sets time in the time stamp input: time - time specified as character string HH:MM:SS sales@amptek.com Page 12 of 15

13 Set date int PmcaSetDate(char *date); int PmcaAsyncSetDate(int *result, char *char); Sets date in the time stamp input: date - date specified as character string MM/DD/YYYY Set lock int PmcaSetLock(int code); int PmcaAsyncSetLock(int *result, int code) Sets the security lock. If the code is zero, the protection is removed and all data is erased. input: code - must not be negative and smaller than 65,536 Set battery type int PmcaSetBatteryType(PmcaBatteryType type); int PmcaAsyncSetBatteryType(int *result, PmcaBatteryType type) The specified main battery type is stored into the status data in PMCA input: type - battery type as defined in PmcaBatteryType Set acquisition time int PmcaSetAcquistionTime(int time); int PmcaAsyncSetAcquisitionTime(int *result, int time) sales@amptek.com Page 13 of 15

14 Presets the acquisition time in seconds, live or real depending on the current timer mode input: time - must be positive and less than 16,777,216 Set threshold int PmcaSetThreshold (short threshold); int PmcaAsyncSetThreshold(int *result, short threshold) Sets the threshold input: threshold - must not be negative and smaller than half of current gain Developing PMCA Application Programs with Visual C++ The first step in developing PMCA application programs in Visual C++ is to create a project. Include in the project the application source files. Add PmcaCom.h header and if error codes are used for diagnostics also include PmcaErr.h. There are two flavors of executable files that can be eventually generated: statically linked executable modules and modules utilizing the PMCA Dynamic Link Library (DLL). In the first case, include PmcaLib.lib library file into the project. In the second case, include PmcaDll.lib. PMCA COM is a multithreaded software component and therefore the system must be configured to use multithreaded system libraries. This can be accomplished by appropriately setting Visual C++ options. On the "settings" dialog select "C/C++" tab, select "Code Generation" category and chose Multithreaded runtime library. Developing PMCA Applications in Visual Basic PMCA COM API functions can be easily imported into Visual Basic programs from PmcaDll.dll by declaring external functions in basic forms. The following lines illustrate declaration of functions PmcaGetData and PmcaAsyncGetData: Option Explicit Private Declare Function PmcaGetData _ Lib "PmcaDll.dll" ( sales@amptek.com Page 14 of 15

15 ByRef buffer as Long, _ ByVal channel as Long, _ ByVal count as Long) as Long Private Declare Function PmcaAsyncGetData _ Lib "PmcaDll.dll" ( ByRef result as Long, ByRef buffer as Long, _ ByVal channel as Long, _ ByVal count as Long) as Long MCA8000A Programmer s Guide (API) Amptek Inc. Both functions, PmcaGetData and PmcaAsyncGetData, can now be used as functions in Basic programs. Lab Windows CVI: NOTE: You cannot use the.lib file created in Microsoft Visual C/C++. You have to use/create a.lib that is compatible with LabWindows. Follow this procedure: 1. Add the header file PmcaCom.h to your project. 2. Open the header file. 3. Go to Options, then select Generate DLL import library. 4. Select PmcaDll.Dll NOTE: It is best to send commands with loops that retry sending the command if the first attempt fails. This is especially necessary under battery operation. See the Visual Basic and C++ examples provided. sales@amptek.com Page 15 of 15