4.5 C99 Program APIs

Overview

The C99 Program APIs cover program start, stop, pause, resume, running-program queries, BasScript execution, and program-pose read/write operations.

Header files:

• include/c_arm_program.h
• include/c_arm_types.h

API Signatures

Arm_Program_Start

int Arm_Program_Start(ArmHandle* h, const char* programName);

Item	Description
Description	Starts the specified program.
Request parameters	h : ArmHandle* , C99 session handle, usually created by Arm_Create() ; service APIs require a successful connection first programName : const char* , name of the program to start; must not be NULL
Return value	Integer STATUS_CODE ; 0 means success, and other values should be handled according to the status-code definitions

Arm_Program_Stop

int Arm_Program_Stop(ArmHandle* h, const char* programName);

Item	Description
Description	Stops the specified program or the current program.
Request parameters	h : ArmHandle* , C99 session handle, usually created by Arm_Create() ; service APIs require a successful connection first programName : const char* , program name; pass NULL or an empty string to stop the currently running program
Return value	Integer STATUS_CODE ; 0 means success, and other values should be handled according to the status-code definitions

Arm_Program_Pause

int Arm_Program_Pause(ArmHandle* h, const char* programName);

Item	Description
Description	Pauses the specified program or the current program.
Request parameters	h : ArmHandle* , C99 session handle, usually created by Arm_Create() ; service APIs require a successful connection first programName : const char* , program name; pass NULL or an empty string to pause the currently running program
Return value	Integer STATUS_CODE ; 0 means success, and other values should be handled according to the status-code definitions

Arm_Program_Resume

int Arm_Program_Resume(ArmHandle* h, const char* programName);

Item	Description
Description	Resumes the specified program or the current program.
Request parameters	h : ArmHandle* , C99 session handle, usually created by Arm_Create() ; service APIs require a successful connection first programName : const char* , program name; pass NULL or an empty string to resume the currently paused program
Return value	Integer STATUS_CODE ; 0 means success, and other values should be handled according to the status-code definitions

Arm_Program_GetAllRunning

int Arm_Program_GetAllRunning(ArmHandle* h, ArmRunningProgramInfo* outArray, size_t maxCount, size_t* outCount);

Item	Description
Description	Queries the list of programs that are currently running.
Request parameters	h : ArmHandle* , C99 session handle, usually created by Arm_Create() ; service APIs require a successful connection first outArray : ArmRunningProgramInfo* , caller-allocated output array maxCount : size_t , capacity of the output array, expressed as the maximum number of elements the caller can receive outCount : size_t* , output-count pointer; on success, receives the actual number of elements
Return value	Integer STATUS_CODE ; 0 means success, and other values should be handled according to the status-code definitions
Notes	The array output is allocated by the caller. maxCount is the capacity, and outCount returns the actual count.

Arm_Program_ExecuteBasScript

int Arm_Program_ExecuteBasScript(ArmHandle* h, const char** lines, size_t lineCount);

Item	Description
Description	Executes BAS script text lines.
Request parameters	h : ArmHandle* , C99 session handle, usually created by Arm_Create() ; service APIs require a successful connection first lines : const char** , array of BAS script text lines; when lineCount > 0 , the array and every line must not be NULL lineCount : size_t , number of script text lines
Return value	Integer STATUS_CODE ; 0 means success, and other values should be handled according to the status-code definitions

Arm_Program_ExecuteBasScriptEx

int Arm_Program_ExecuteBasScriptEx(ArmHandle* h, const ArmBasScript* script);

Item	Description
Description	Executes a structured BasScript object.
Request parameters	h : ArmHandle* , C99 session handle, usually created by Arm_Create() ; service APIs require a successful connection first script : const ArmBasScript* , structured BasScript parameters
Return value	Integer STATUS_CODE ; 0 means success, and other values should be handled according to the status-code definitions

Arm_ProgramPose_Read

int Arm_ProgramPose_Read(ArmHandle* h, const char* programName, int32_t index, int32_t programType, ArmProgramPose* outPose);

Item	Description
Description	Reads the specified program pose.
Request parameters	h : ArmHandle* , C99 session handle, usually created by Arm_Create() ; service APIs require a successful connection first programName : const char* , program name; must not be NULL index : int32_t , program-pose index programType : int32_t , program type; see ArmProgramType for values outPose : ArmProgramPose* , pose output-structure pointer
Return value	Integer STATUS_CODE ; 0 means success, and other values should be handled according to the status-code definitions

Arm_ProgramPose_Write

int Arm_ProgramPose_Write(ArmHandle* h, const char* programName, int32_t index, int32_t programType, const ArmProgramPose* pose);

Item	Description
Description	Writes the specified program pose.
Request parameters	h : ArmHandle* , C99 session handle, usually created by Arm_Create() ; service APIs require a successful connection first programName : const char* , program name; must not be NULL index : int32_t , program-pose index programType : int32_t , program type; see ArmProgramType for values pose : const ArmProgramPose* , program pose to write
Return value	Integer STATUS_CODE ; 0 means success, and other values should be handled according to the status-code definitions

Arm_ProgramPose_Add

int Arm_ProgramPose_Add(ArmHandle* h, const char* programName, int32_t index, int32_t programType, const ArmProgramPose* pose);

Item	Description
Description	Adds a program pose.
Request parameters	h : ArmHandle* , C99 session handle, usually created by Arm_Create() ; service APIs require a successful connection first programName : const char* , program name; must not be NULL index : int32_t , insertion index for the new pose programType : int32_t , program type; see ArmProgramType for values pose : const ArmProgramPose* , program pose to add
Return value	Integer STATUS_CODE ; 0 means success, and other values should be handled according to the status-code definitions

Arm_ProgramPose_ReadAll

int Arm_ProgramPose_ReadAll(ArmHandle* h, const char* programName, int32_t programType, ArmProgramPose* outArray, size_t maxCount, size_t* outCount);

Item	Description
Description	Reads all poses from the specified program.
Request parameters	h : ArmHandle* , C99 session handle, usually created by Arm_Create() ; service APIs require a successful connection first programName : const char* , program name; must not be NULL programType : int32_t , program type; see ArmProgramType for values outArray : ArmProgramPose* , caller-allocated output array maxCount : size_t , capacity of the output array, expressed as the maximum number of elements the caller can receive outCount : size_t* , output-count pointer; on success, receives the actual number of elements
Return value	Integer STATUS_CODE ; 0 means success, and other values should be handled according to the status-code definitions
Notes	The array output is allocated by the caller. maxCount is the capacity, and outCount returns the actual count.

Arm_ProgramPose_WriteBatch

int Arm_ProgramPose_WriteBatch(ArmHandle* h, const char* programName, const ArmProgramPose* poses, size_t count);

Item	Description
Description	Writes program poses in a batch.
Request parameters	h : ArmHandle* , C99 session handle, usually created by Arm_Create() ; service APIs require a successful connection first programName : const char* , program name; must not be NULL poses : const ArmProgramPose* , array of program poses; when count > 0 , it must not be NULL count : size_t , number of array elements
Return value	Integer STATUS_CODE ; 0 means success, and other values should be handled according to the status-code definitions

Arm_ProgramPose_Convert

int Arm_ProgramPose_Convert(ArmHandle* h, const ArmProgramPose* inPose, int32_t fromType, int32_t toType, ArmProgramPose* outPose);

Item	Description
Description	Converts a program pose type.
Request parameters	h : ArmHandle* , C99 session handle, usually created by Arm_Create() ; service APIs require a successful connection first inPose : const ArmProgramPose* , input pose or point-structure pointer fromType : int32_t , source pose type toType : int32_t , target pose type outPose : ArmProgramPose* , pose output-structure pointer
Return value	Integer STATUS_CODE ; 0 means success, and other values should be handled according to the status-code definitions

Semantic Rules

ArmProgramType

Enum value	Value	Description
ARM_PROGRAM_USER	0	User program
ARM_PROGRAM_BLOCK	1	Block program

ArmRunningProgramInfo

Field	Type	Description
threadId	int32_t	Program execution thread ID
programName	char[128]	Program name
xpath	char[256]	Program node path
programStatus	int32_t	Program running status
programType	char[32]	Program type string

ArmBasScript

Field	Type	Description
name	const char*	Script name; treated as an empty string when NULL
lines	const char**	Array of script text lines
lineCount	size_t	Number of script text lines
flagIf	int32_t	IF-structure closing counter
flagSwitch	int32_t	SWITCH-structure closing counter
flagWhile	int32_t	WHILE-structure closing counter

ArmProgramPose

Field	Type	Description
id	int32_t	Program-pose ID
name	char[128]	Program-pose name
comment	char[256]	Program-pose comment
pose	ArmMotionPose	Pose data for the point
uf	int32_t	User coordinate-system number
tf	int32_t	Tool coordinate-system number

Program Execution

Scenario	Rule
Arm_Program_Start	Returns PROGRAM_NOT_FOUND when the program does not exist
Arm_Program_Stop / Pause / Resume	Passing NULL or an empty string as programName applies the operation to the current program
Arm_Program_GetAllRunning	Supports count-only mode with outArray == NULL
Arm_Program_ExecuteBasScript	Executes the text lines provided by the caller as-is
Arm_Program_ExecuteBasScriptEx	Checks that the ArmBasScript structure is properly closed; after validation, it appends RETURN / END automatically

Program Poses

Scenario	Return
Program does not exist	PROGRAM_NOT_FOUND
Pose does not exist	PROGRAM_POSE_NOT_FOUND
Batch-writing block-program poses	UNSUPPORTED_FILETYPE
Batch-writing an empty array	INVALID_PARAMETER

Arm_ProgramPose_ReadAll() supports count-only mode with outArray == NULL . If the buffer capacity is smaller than the actual number of poses, it returns BUFFER_TOO_SMALL . Write, add, and batch-write operations modify controller program content; confirm the target program and pose index before executing them.

Minimal Example

#include <stdio.h>  // Provides printf for printing the number of running programs.
#include "c_arm_api.h"  // Includes the aggregate C99 SDK header.
int main(void)  // Example program entry point.
{  // Enters the example main function.
    ArmHandle* h = Arm_Create();  // Creates a C99 session handle.
    ArmRunningProgramInfo programs[8] = {0};  // Prepares the running-program array.
    size_t count = 0U;  // Prepares the output program count.
    if (h == NULL) {  // Checks whether handle creation failed.
        return 1;  // Exits when creation fails.
    }  // Ends the handle check.
    if (Arm_Connect(h, "10.27.1.2", "10.27.1.102") != 0) {  // Connects to the controller.
        Arm_Destroy(h);  // Releases the handle after connection failure.
        return 1;  // Returns an error.
    }  // Ends the connection check.
    int ret = Arm_Program_GetAllRunning(h, programs, 8, &count);  // Queries running programs.
    printf("running_count=%zu\n", count);  // Prints the number of running programs.
    Arm_Disconnect(h);  // Disconnects from the controller.
    Arm_Destroy(h);  // Destroys the handle.
    return ret == 0 ? 0 : 1;  // Returns according to the query result.
}  // Ends the example main function.

Scenario Examples

Query Running Programs

size_t requiredCount = 0U;  // Prepares the running-program count output.
int countRet = Arm_Program_GetAllRunning(h, NULL, 0, &requiredCount);  // Queries only the count.
ArmRunningProgramInfo programs[16] = {0};  // Prepares the running-program array.
size_t actualCount = 0U;  // Prepares the number of elements actually written.
int listRet = Arm_Program_GetAllRunning(h, programs, 16, &actualCount);  // Queries running-program details.
(void)countRet;  // Keeps the count-query status code in this example.
(void)listRet;  // Keeps the list-query status code in this example.

Execute BasScript Text

const char* lines[] = {  // Prepares BAS script text lines.
    "WAIT SEC 0.1"  // Waits for 0.1 seconds.
};  // Ends the script-line array.
/* int execRet = Arm_Program_ExecuteBasScript(h, lines, 1); */  // Executing a script changes controller state; execute only after confirmation.
ArmBasScript script = {0};  // Prepares the structured script parameters.
script.name = "demo.bas";  // Sets the script name.
script.lines = lines;  // Sets the script-line array.
script.lineCount = 1;  // Sets the number of script lines.
/* int execExRet = Arm_Program_ExecuteBasScriptEx(h, &script); */  // Executes the structured script; execute only after confirmation.

Read and Write Program Poses

ArmProgramPose pose = {0};  // Prepares the program-pose structure.
int readRet = Arm_ProgramPose_Read(h, "demo", 1, ARM_PROGRAM_USER, &pose);  // Reads program pose 1.
ArmProgramPose converted = {0};  // Prepares the converted program pose.
int convertRet = Arm_ProgramPose_Convert(h, &pose, ARM_POSE_TYPE_JOINT, ARM_POSE_TYPE_CART, &converted);  // Converts the pose type.
ArmProgramPose poses[2] = {0};  // Prepares the batch-write pose array.
/* int writeRet = Arm_ProgramPose_Write(h, "demo", 1, ARM_PROGRAM_USER, &pose); */  // Writing a pose modifies the program; execute only after confirmation.
/* int addRet = Arm_ProgramPose_Add(h, "demo", 2, ARM_PROGRAM_USER, &pose); */  // Adding a pose modifies the program; execute only after confirmation.
/* int batchRet = Arm_ProgramPose_WriteBatch(h, "demo", poses, 2); */  // Batch-writing poses modifies the program; execute only after confirmation.
(void)readRet;  // Keeps the read status code in this example.
(void)convertRet;  // Keeps the conversion status code in this example.

Control Program Execution

/* int startRet = Arm_Program_Start(h, "demo"); */  // Starting a program changes controller execution state; execute only after confirmation.
/* int pauseRet = Arm_Program_Pause(h, NULL); */  // Pauses the current program; execute only after confirmation.
/* int resumeRet = Arm_Program_Resume(h, NULL); */  // Resumes the current program; execute only after confirmation.
/* int stopRet = Arm_Program_Stop(h, NULL); */  // Stops the current program; execute only after confirmation.

Sample code

c99/program_execution/src/main.cpp

#include <stdio.h>
#include <string.h>

extern "C" {
#include "c_arm_api.h"
}

int main(void)
{
    // [ZH] 本示例直接在源码中写死连接地址，不解析命令行参数。
    // [EN] This example hard-codes the connection addresses in the source code and does not parse command-line arguments.
    // [ZH] 创建并连接 SDK 句柄。
    // [EN] Create the SDK handle and connect to the robot.
    ArmHandle* handle = Arm_Create();
    if (handle == NULL) {
        printf("[c99_program] 创建句柄失败 / Failed to create the handle\n");
        return 1;
    }
    int ret = Arm_Connect(handle, "10.27.1.2", "10.27.1.102");
    if (ret != 0) {
        printf("[c99_program] 连接失败 / Connect failed, 状态码 / Status code: %d\n", ret);
        Arm_Destroy(handle);
        return 1;
    }
    printf("[c99_program] 机器人连接成功 / Robot connected successfully\n");

    // [ZH] 查询全部运行中程序。
    // [EN] Query all running programs.
    ArmRunningProgramInfo runningPrograms[8] = {0};
    size_t runningCount = 0U;
    ret = Arm_Program_GetAllRunning(handle, runningPrograms, 8U, &runningCount);
    printf("[c99_program] GetAllRunning 状态码 / GetAllRunning status code: %d, 数量 / Count: %zu\n", ret, runningCount);
    for (size_t index = 0U; index < runningCount; ++index) {
        printf("[c99_program] 运行中程序 / Running program #%zu: thread_id=%d, name=%s, xpath=%s, status=%d, type=%s\n",
            index,
            runningPrograms[index].threadId,
            runningPrograms[index].programName,
            runningPrograms[index].xpath,
            runningPrograms[index].programStatus,
            runningPrograms[index].programType);
    }

    // [ZH] 直接执行程序控制接口。
    // [EN] Execute the program control APIs directly.
    ret = Arm_Program_Start(handle, "demo.bas");
    printf("[c99_program] Start 状态码 / Start status code: %d\n", ret);
    ret = Arm_Program_Pause(handle, "demo.bas");
    printf("[c99_program] Pause 状态码 / Pause status code: %d\n", ret);
    ret = Arm_Program_Resume(handle, "demo.bas");
    printf("[c99_program] Resume 状态码 / Resume status code: %d\n", ret);
    ret = Arm_Program_Stop(handle, "demo.bas");
    printf("[c99_program] Stop 状态码 / Stop status code: %d\n", ret);

    // [ZH] 顺序执行 BAS 脚本接口。
    // [EN] Execute the BAS script APIs in sequence.
    const char* lines[3] = {
        "PRINT \"SDK example\"",
        "WAIT 0.1",
        "END"
    };
    ArmBasScript script = {0};
    script.name = "example_bas_script.bas";
    script.lines = lines;
    script.lineCount = 3U;
    ret = Arm_Program_ExecuteBasScript(handle, lines, 3U);
    printf("[c99_program] ExecuteBasScript 状态码 / ExecuteBasScript status code: %d\n", ret);
    ret = Arm_Program_ExecuteBasScriptEx(handle, &script);
    printf("[c99_program] ExecuteBasScriptEx 状态码 / ExecuteBasScriptEx status code: %d\n", ret);

    // [ZH] 构造程序点位并顺序执行全部 ProgramPose 接口。
    // [EN] Build a program pose and execute all ProgramPose APIs in sequence.
    ArmProgramPose pose = {0};
    ArmProgramPose readPose = {0};
    ArmProgramPose convertedPose = {0};
    ArmProgramPose poseList[8] = {0};
    size_t poseCount = 0U;
    pose.id = 1;
    snprintf(pose.name, sizeof(pose.name), "P1");
    snprintf(pose.comment, sizeof(pose.comment), "sdk example");
    pose.pose.poseType = ARM_POSE_TYPE_JOINT;
    pose.pose.jointSize = 6;
    pose.uf = 0;
    pose.tf = 0;
    ret = Arm_Motion_GetCurrentPose(handle, ARM_POSE_TYPE_JOINT, &pose.pose);
    printf("[c99_program] GetCurrentPose(for pose) 状态码 / GetCurrentPose(for pose) status code: %d\n", ret);
    ret = Arm_ProgramPose_Convert(handle, &pose, ARM_POSE_TYPE_JOINT, ARM_POSE_TYPE_CART, &convertedPose);
    printf("[c99_program] ProgramPose_Convert 状态码 / ProgramPose_Convert status code: %d\n", ret);
    ret = Arm_ProgramPose_Read(handle, "demo.bas", 1, ARM_PROGRAM_USER, &readPose);
    printf("[c99_program] ProgramPose_Read 状态码 / ProgramPose_Read status code: %d, id=%d, name=%s\n", ret, readPose.id, readPose.name);
    ret = Arm_ProgramPose_Write(handle, "demo.bas", 1, ARM_PROGRAM_USER, &pose);
    printf("[c99_program] ProgramPose_Write 状态码 / ProgramPose_Write status code: %d\n", ret);
    ret = Arm_ProgramPose_Add(handle, "demo.bas", 2, ARM_PROGRAM_USER, &pose);
    printf("[c99_program] ProgramPose_Add 状态码 / ProgramPose_Add status code: %d\n", ret);
    ret = Arm_ProgramPose_ReadAll(handle, "demo.bas", ARM_PROGRAM_USER, poseList, 8U, &poseCount);
    printf("[c99_program] ProgramPose_ReadAll 状态码 / ProgramPose_ReadAll status code: %d, 数量 / Count: %zu\n", ret, poseCount);
    if (poseCount == 0U) {
        poseList[0] = pose;
        poseCount = 1U;
    }
    ret = Arm_ProgramPose_WriteBatch(handle, "demo.bas", poseList, poseCount);
    printf("[c99_program] ProgramPose_WriteBatch 状态码 / ProgramPose_WriteBatch status code: %d\n", ret);

    // [ZH] 断开连接并销毁句柄。
    // [EN] Disconnect and destroy the handle.
    Arm_Disconnect(handle);
    Arm_Destroy(handle);
    printf("[c99_program] 示例结束 / Example finished\n");
    return 0;
}