Skip to content

ChemStation Macros - Complete Guide

Comprehensive guide to ChemStation's built-in scripting capabilities for automation of analytical workflows.

Overview

ChemStation includes a command processor (CP) that interprets and executes commands interactively or through scripts. This guide provides hands-on examples and best practices for creating automation solutions.

1. ChemStation Commands

Basic Command Syntax

Display Messages: 

Print "This is a message"

Multiple Commands per Line: Separate commands with semicolons (;): 

Print "Starting"; Sleep 2; Print "Complete"

Comments: Text after ! is ignored: 

! This is a comment
Print "Active command"  ! End-of-line comment

Command History: Use ↑ and ↓ arrow keys to navigate through previous commands in the command processor.

2. Macro Structure and Parameters

Macros are named collections of commands that automate repetitive tasks and complex workflows.

Basic Macro Structure

Name MyMessage
    Print "Hello World!"
EndMacro

Macro Parameters

Macros can accept parameters for flexible operation:

Name InjectSample
    Parameter SampleName$, VialPos, InjVol
    Print "Sample=", SampleName$, ", Vial=", VialPos, ", InjVol=", InjVol
EndMacro

Calling the macro: 

InjectSample "Std_1", 5, 10

Local Variables

Define local variables within macros:

Name CalculateVolume
    Local Area, Volume, Concentration
    Area = 2.5
    Concentration = 0.1
    Volume = Area * Concentration * 10
    Print "Calculated Volume =", Volume
EndMacro

Variable Scope:

  • Local variables exist only within the macro
  • Global variables persist throughout the ChemStation session
  • Use local variables to prevent naming conflicts

3. Loading and Managing Macros

Loading Macros

Load from relative path: 

Macro "mymacro.mac"

Load from absolute path: 

Macro "D:\projects\chem\automation\mymacro.mac"

Executing Macros

Run without parameters: 

MyMessage

Run with parameters: 

InjectSample "Sample_A", 3, 5.0

Macro Management

Remove macro from memory: 

Remove MyMessage

List loaded macros: 

Show Macros

4. Variables and Data Types

Variable Types

String Variables: 

Sample$ = "Test_Sample_001"
DataPath$ = "C:\ChemStation\Data\"

Numeric Variables: 

Flow = 1.5
Temperature = 25.0
InjectionVolume = 10

System Variables

ChemStation provides built-in system variables for accessing current state information:

Common System Variables:

  • _DataFile$ - Current data file name
  • _MethodOn - Method status (0=off, 1=on)
  • _SequenceOn - Sequence status (0=off, 1=on)
  • _AutoPath$ - Automatic data path
  • _Instrument$ - Current instrument configuration

Display all system variables: 

Show Variables

5. Registry Operations

Registries are ChemStation's primary data containers, storing complex information about analyses, methods, chromatograms, and spectra.

Understanding Registry Structure

Registry Hierarchy:

  • Registry - Top-level container (e.g., ChromReg for chromatograms)
  • Objects - Individual data items within registry (e.g., ChromReg[1])
  • Headers - Metadata about objects
  • Data Blocks - Raw analytical data
  • Tables - Processed results (peaks, quantification)

Basic Registry Operations

Check registry size: 

Print RegSize(ChromReg)

List registry contents: 

Print RegCont$(ChromReg)

Access specific registry object: 

ChromReg[1]  ! Access first chromatogram

Reading Data from Registries

Extract raw data points: 

Data(ChromReg[1], 0, 10)  ! X-axis value at point 10
Data(ChromReg[1], 1, 10)  ! Y-axis value at point 10

Read header information: 

Print ObjHdrVal$(ChromReg[1], "SampleName")
Print ObjHdrVal(ChromReg[1], "InjectionVolume")

Working with Tables

Read text from tables: 

TabText$(ChromRes[1], "Peak", 2, "Name")    ! Peak name for peak #2

Read numeric values from tables: 

TabVal(ChromRes[1], "Peak", 2, "Area")      ! Peak area for peak #2
TabVal(ChromRes[1], "Peak", 2, "RT")        ! Retention time for peak #2

Modifying Registry Data

Update header values: 

SetObjHdrVal ChromReg[1], "Title", "My Custom Chromatogram"
SetObjHdrVal ChromReg[1], "SampleInfo", "Batch_2024_001"

Modify data points: 

SetData ChromReg[1], 1, 10, 1500.5  ! Set Y-value at point 10

6. RC.NET Module Control

RC.NET provides standardized communication with ChemStation modules like pumps, detectors, and autosamplers.

RC.NET Registry Structure

Each module maintains three primary registries:

Registry Types:

  • RC<ModID><#>Method - Method parameters and settings
  • RC<ModID><#>Status - Real-time status information (pressures, temperatures)
  • RC<ModID><#>Config - Module configuration (type, firmware version, serial number)

Example Module Identifiers:

  • PMP1 - Quaternary Pump
  • WLS1 - UV-Vis Detector
  • ALS1 - Autosampler
  • CE1 - Capillary Electrophoresis

Method Parameter Modification

Standard method parameter workflow: 

! Upload current method to memory
UploadRCMethod PMP1

! Modify parameters
SetObjHdrVal RCPMP1Method[1], "StopTime_Time", 10
SetObjHdrVal RCPMP1Method[1], "Flow", 1.0

! Download modified method to instrument
DownloadRCMethod PMP1

Common Method Parameters:

  • Flow rates: "Flow", "Flow_A", "Flow_B"
  • Temperatures: "Temperature", "ColTemp"
  • Times: "StopTime_Time", "PostTime"
  • Volumes: "InjVol", "MaxInjVol"

Reading Module Status

Current operational parameters: 

Print ObjHdrVal(RCPMP1Status[1], "Pressure")     ! Current pressure
Print ObjHdrVal(RCPMP1Status[1], "Flow_actual")  ! Actual flow rate
Print ObjHdrVal(RCWLS1Status[1], "Lamp")         ! Lamp status

Module configuration information: 

Print ObjHdrVal(RCPMP1Config[1], "SerialNumber")   ! Serial number
Print ObjHdrVal(RCPMP1Config[1], "FirmwareRev")    ! Firmware version

Direct Module Communication

Send command without response: 

WriteModule "CE1", "LRPL 10"  ! Load replenishment position 10

Send command and get response: 

Response$ = SendModule$("CE1", "LIFTER:OCCUPIED? 3")  ! Check vial position
Print "Vial occupied:", Response$

Advanced module interrogation: 

Print SendModule$("PMP1", "PRES?")     ! Query current pressure
Print SendModule$("ALS1", "INJ:STAT?")  ! Query injection status

7. Discovering Module Commands Through Trace Logs

Module-specific commands can be discovered by monitoring ChemStation's communication logs.

Practical Example - Vial Loading

Sample log entry for loading vial 50 to replenishment position: 

EventId: 228808;Timestamp: 22/07/2025 8:21:16.851;Thread Id: 25;
Message: LDT SendInstruction: Module:[G7150A:DEDAD01310]; 
Instruction:[RRPL]; Reply:[[G7150A:DEDAD01310:IN]: RA 00000 RRPL];
Category: Agilent.LCDrivers.Common.ModuleAccess, Debug;Priority: 3;
Process Name: C:\Chem32\CORE\ChemMain.exe;
Extended Properties: ModuleShortname - Agilent.LCDrivers.Common.ModuleAccess;

Key Information:

  • Module ID: G7150A:DEDAD01310 (CE1)
  • Command: LRPL 50 (Load Replenishment Position 50)
  • Response: RA 00000 (Response Acknowledge - Success)

Trace Analysis Workflow

1. Monitor during operations:

  • Perform action in ChemStation interface (load vial, change parameter)
  • Check C:\Chem32\1\TEMP\rcdriver.trc

2. Extract commands:

  • Look for Instruction: entries
  • Note the exact module ID and command syntax

3. Test in Command Processor: 

WriteModule "CE1", "LRPL 50"  ! Load vial 50 to replenishment

Common Commands Discovered:

  • LRPL n - Load replenishment position
  • LIFTER:OCCUPIED? n - Check if vial n is present

8. Practical Examples

Complete Sample Analysis Macro

Name AnalyzeSample
    Parameter VialNumber, SampleName$, MethodName$
    Local Response$

    ! Load sample vial
    WriteModule "CE1", "INLT " + Val$(VialNumber)
    Sleep 3

    ! Check vial loaded
    Response$ = SendModule$("CE1", "LIFTER:OCCUPIED? 1")
    If Response$ = "0" Then
        Print "Error: Sample vial not loaded"
        Return
    EndIf

    ! Load method
    LoadMethod _METHPATH$, MethodName$ + ".M"

    ! Set sample name
    _SAMPLE$ = SampleName$

    ! Run analysis
    RunMethod _DATAPATH$,, SampleName$

    ! Wait for completion
    While _MethodOn = 1
        Sleep 10
    EndWhile

    ! Unload vial
    WriteModule "CE1", "RINL"

    Print "Analysis of ", SampleName$, " complete"

EndMacro

Registry Data Extraction

Name ExtractPeakData
    Parameter ChromNumber
    Local PeakCount, i, RT, Area, Name$

    ! Get number of peaks
    PeakCount = TabSize(ChromRes[ChromNumber], "Peak")

    Print "Peak Report for Chromatogram ", ChromNumber
    Print "RT(min)", Chr$(9), "Area", Chr$(9), "Name"

    ! Extract each peak
    For i = 1 To PeakCount
        RT = TabVal(ChromRes[ChromNumber], "Peak", i, "RT")
        Area = TabVal(ChromRes[ChromNumber], "Peak", i, "Area")
        Name$ = TabText$(ChromRes[ChromNumber], "Peak", i, "Name")

        Print RT, Chr$(9), Area, Chr$(9), Name$
    Next i

EndMacro

System Status Monitor

Name MonitorSystem
    Local Status$, Pressure, Temperature

    While _MethodOn = 1
        ! Get system status
        Status$ = ObjHdrText$(RCCE1Status[1], "RunState")
        Pressure = ObjHdrVal(RCCE1Status[1], "Pressure")
        Temperature = ObjHdrVal(RCCE1Status[1], "Temperature")

        Print "Status: ", Status$, " | Pressure: ", Pressure, " | Temp: ", Temperature

        Sleep 30  ! Check every 30 seconds
    EndWhile

    Print "Analysis complete"

EndMacro

9. Quick Troubleshooting

Common Issues

Module communication fails:

  • Verify module is online: Print RCModuleReady("PMP1")
  • Restart ChemStation if persistent errors

Registry errors:

  • Check registry exists: Print RegSize(ChromReg)
  • Verify object number: Print RegCont$(ChromReg)

Command not working:

  • Test in Command Processor first
  • Check trace logs for exact syntax
  • Verify module ID matches your system

Quick Reference Commands

Show                          ! List all variables
RCListDevices$()             ! List RC.NET modules  
Print RegCont$(ChromReg)     ! Show registry contents
Remove MacroName             ! Unload macro

10. Advanced Registry Exploration

For comprehensive registry exploration, use the provided register_reader.mac utility to examine all available registry structures and data. This tool provides:

  • Interactive registry browsing
  • Object structure examination
  • Header and table data inspection
  • Registry modification capabilities

Loading the registry reader: 

# From Python API
api.system.add_register_reader()

# Then in ChemStation:
# Menu → Debug → Show Registers

This tool is invaluable for understanding ChemStation's internal data structures and developing advanced automation scripts.